前端工程化 / 知识点
pnpm / npm 包管理速查手册
环境与初始化
node --version; npm --version; pnpm --version确认 Node.js、npm、pnpm 的版本、安装路径和当前生效配置。
查看版本与环境
用于确认当前终端实际调用的 Node.js、npm、pnpm,以及它们的可执行文件、仓库、缓存和全局目录。遇到“本机正常、CI 失败”“升级后版本没变化”或依赖从错误镜像下载时,先执行本条目。
macOS 与 Linux 一次性检查
printf 'Node: '; node --version
printf 'npm: '; npm --version
printf 'pnpm: '; pnpm --version
printf '\nNode executable: '; node -p "process.execPath"
printf 'npm executable: '; command -v npm
printf 'pnpm executable: '; command -v pnpm
printf '\nnpm registry: '; npm config get registry
printf 'npm cache: '; npm config get cache
printf 'npm prefix: '; npm prefix -g
printf 'npm root: '; npm root -g
printf '\npnpm registry: '; pnpm config get registry
printf 'pnpm store: '; pnpm store path
printf 'pnpm global bin: '; pnpm bin -g预期输出
Node: v<MAJOR>.<MINOR>.<PATCH>
npm: <MAJOR>.<MINOR>.<PATCH>
pnpm: <MAJOR>.<MINOR>.<PATCH>
Node executable: <PATH>/node
npm executable: <PATH>/npm
pnpm executable: <PATH>/pnpm
npm registry: https://registry.npmjs.org/
npm cache: <PATH>/.npm
npm prefix: <PATH>
npm root: <PATH>/lib/node_modules
pnpm registry: https://registry.npmjs.org/
pnpm store: <PATH>/pnpm/store/v<MAJOR>
pnpm global bin: <PATH>版本号和路径会因操作系统、Node 版本管理器及安装方式不同而变化。重点检查三个版本是否符合项目要求,以及 node、npm、pnpm 是否来自同一套预期环境。
Windows PowerShell 检查路径
node --version
npm --version
pnpm --version
Get-Command node,npm,pnpm | Select-Object Name,Source
npm config get registry
npm config get cache
pnpm config get registry
pnpm store path
pnpm bin -g预期输出
v<MAJOR>.<MINOR>.<PATCH>
<MAJOR>.<MINOR>.<PATCH>
<MAJOR>.<MINOR>.<PATCH>
Name Source
---- ------
node.exe <PATH>\node.exe
npm.cmd <PATH>\npm.cmd
pnpm.cmd <PATH>\pnpm.cmd
https://registry.npmjs.org/
<PATH>\npm-cache
https://registry.npmjs.org/
<PATH>\pnpm\store\v<MAJOR>
<PATH>\pnpmSource 是当前命令解析到的实际文件。若同一命令存在多个副本,继续运行 Get-Command -All pnpm,优先处理排在最前面的旧路径。
输出读取
node -p "process.execPath" 显示 Node 可执行文件;npm prefix -g 是 npm 全局前缀,npm root -g 是全局包目录。pnpm store path 是内容寻址存储,pnpm bin -g 是全局命令目录。
需要查看配置来源时,使用 npm config get userconfig、npm config get globalconfig 和 pnpm config get globalconfig。npm 配置可能来自命令行、环境变量、项目 .npmrc、用户 .npmrc 和全局配置;pnpm 的仓库与认证仍可来自 .npmrc,其他新配置主要位于 pnpm-workspace.yaml 或全局 YAML 配置。
风险与排障
不要直接粘贴完整 .npmrc 到工单或聊天中,其中可能包含私有仓库令牌。安全替代方案是只读取 registry、cache、prefix 等非敏感键,并在分享前检查输出。
版本正确但命令路径异常,通常是 PATH 中残留了旧 Node、全局 pnpm 或 Corepack shim。先定位全部同名命令,再删除或调整确认无用的旧路径;不要直接清空系统目录。pnpm: command not found 时,先确认 Node 和 Corepack,再启用 Corepack 或重新安装 pnpm。
corepack enable [--install-directory <path>] [pnpm]; corepack use pnpm@<version>通过 Corepack 安装并固定项目使用的 pnpm 版本。
启用 Corepack
用于让项目通过 package.json 固定 pnpm 版本,避免开发机和 CI 使用不同主版本。流程会安装或更新 Corepack、创建 pnpm shim,并把解析出的精确 pnpm 版本写入项目。
主流程
在包含 package.json 的项目根目录执行。当前稳定线使用 pnpm 11;latest-11 会解析为一个精确版本并写入项目。
npm install --global corepack@latest
corepack enable pnpm
corepack use pnpm@latest-11
printf 'Corepack: '; corepack --version
printf 'pnpm: '; pnpm --version
printf 'Pinned: '; node -p "require('./package.json').packageManager"预期输出
added <COUNT> package in <TIME>
<Corepack/pnpm installation logs>
Corepack: <MAJOR>.<MINOR>.<PATCH>
pnpm: 11.<MINOR>.<PATCH>
Pinned: pnpm@11.<MINOR>.<PATCH>+sha512.<HASH>packageManager 也可能不带哈希,取决于 Corepack 版本。只要其中记录了精确的 pnpm@x.y.z,并且 pnpm --version 与其一致,固定即已生效。
生效行为
corepack enable pnpm 在 Corepack 所在目录旁创建 pnpm shim。进入含 packageManager 字段的项目后,执行 pnpm 会选择该项目声明的版本;其他项目可以声明不同版本。
corepack use pnpm@latest-11 会修改 package.json,并自动执行一次安装。运行前应确保工作区可提交或可回滚,完成后提交 package.json 与 pnpm-lock.yaml,让本地和 CI 使用同一版本。
常用变体
需要严格使用团队给定版本时,将命令改为 corepack use pnpm@<EXACT_VERSION>。升级当前项目到同一主版本的最新可用版本,可执行 corepack up;升级前先检查 pnpm 发布说明并在独立分支验证锁文件变化。
只想设置项目外的系统默认版本、不修改当前项目时,使用 corepack install -g pnpm@latest-11。项目存在 packageManager 时,项目声明仍优先。
风险与边界
Node.js 25 及更高版本不再随 Node 分发 Corepack,必须先用 npm 单独安装;较早的 Node 即使自带 Corepack,也建议更新后再启用,以避免旧签名数据导致下载失败。pnpm 11 的普通 Node.js 包要求 Node 22 或更高版本;Node 18 或 20 项目应固定 pnpm 10,而不是强行升级运行时。
npm install --global 或 corepack enable 出现权限错误,说明 Node 安装目录不可写。安全替代方案是使用 nvm、fnm、Volta 等版本管理器安装到用户目录;不要默认用 sudo 覆盖系统 Node。
若 pnpm --version 与 packageManager 不一致,检查 command -v pnpm 或 Get-Command -All pnpm。旧的全局 pnpm 可能排在 Corepack shim 前面;确认来源后再卸载旧副本或调整 PATH,不要盲目删除所有 pnpm 文件。
截至当前 pnpm 文档,Corepack 不能安装 pnpm 12 beta。生产项目应继续固定 pnpm 11,或按 pnpm 官方的非 Corepack 安装方式单独评估 beta。
npm init [--yes]; pnpm init创建 package.json 并设置项目名称、版本和入口等基础信息。
初始化项目
在新目录中创建 package.json,再显式设置名称、版本、入口、模块类型和私有标记。npm init -y 会跳过问答直接使用默认值;pnpm init 也会生成清单文件。:contentReference[oaicite:0]{index=0}
基本语法
交互式初始化适合第一次确认字段;自动化脚本优先使用无交互命令,再用 pkg set 精确修改。
mkdir demo-app
cd demo-app
npm init -y
npm pkg set name=demo-app version=0.1.0 main=src/index.js type=module
npm pkg set private=true --json
npm pkg get name version main type private预期输出
{
"name": "demo-app",
"version": "0.1.0",
"main": "src/index.js",
"type": "module",
"private": true
}npm pkg set 可一次修改多个字段;布尔值、数字、数组或对象要配合 --json,否则通常会按字符串写入。:contentReference[oaicite:1]{index=1}
高频用法
- 逐项确认字段:运行
npm init,按提示输入名称、版本、入口和许可证。 - 快速创建应用:运行
npm init -y,随后设置"private": true,避免误发布内部项目。 - 使用 pnpm:运行
pnpm init;pnpm 11.3 及以上可用pnpm pkg set name=demo-app修改字段。:contentReference[oaicite:2]{index=2} - 初始化工作区子包:在 npm 工作区根目录执行
npm init -w packages/api,同时创建子目录清单并更新根工作区配置。:contentReference[oaicite:3]{index=3}
关键字段
name 应使用小写、无空格的包名;version 使用语义化版本;main 指向实际存在的入口文件;type=module 表示 .js 默认按 ES Module 解析;仅内部使用的项目应设置 private=true。
风险与边界
在已有项目执行初始化可能保留或补充现有字段,后续 pkg set 会覆盖同名字段。修改前先提交版本控制或备份 package.json,不要在不清楚发布流程时批量改写 name、version 和 type。
npm init <名称> 不一定是普通初始化,它会解析并执行对应的 create-<名称> 初始化器。只想创建基础 package.json 时,使用不带名称的 npm init 或 npm init -y。:contentReference[oaicite:4]{index=4}
排障清单
- 出现
ENOENT:确认当前目录可写,并检查是否在预期项目目录。 - 字段类型错误:用
npm pkg get <字段>检查;布尔值或数字重新使用--json写入。 - 入口启动失败:确认
main指向的文件已经创建,并检查type与代码中的import、require是否一致。 - 包名被拒绝:改为小写字母、数字、连字符或合法作用域名称,例如
@team/demo-app。
速查:先初始化,再用 pkg set 校正字段,最后用 pkg get 读取验证。
npm config get registry; npm config set registry <url> [--location=user|project]; pnpm config get registry查看、切换和恢复 npm registry,并区分全局与项目级配置。
配置镜像源
安装依赖缓慢、需要企业私有仓库或临时切换下载源时,先查看当前 registry,再明确写入项目级或用户级配置。npm 默认公共源为 https://registry.npmjs.org/。 :contentReference[oaicite:5]{index=5}
查看与切换
下面只修改当前项目的 registry,不影响同一用户的其他项目。
npm config get registry
npm config set registry=https://registry.npmmirror.com --location=project
npm config get registry --location=project预期输出
https://registry.npmjs.org/
https://registry.npmmirror.com第一行是切换前的有效源,第二行是项目级配置值。npm 的 --location 可取 project、user 或 global;不指定时,npm config set 默认修改用户配置。:contentReference[oaicite:6]{index=6}
高频用法
项目级配置适合团队统一依赖源,通常写入项目根目录 .npmrc:
registry=https://registry.npmmirror.com验证方法
npm config get registry --location=project
pnpm config get registry预期输出
https://registry.npmmirror.com
https://registry.npmmirror.comnpm 会读取项目根目录 .npmrc;pnpm 的 registry 与认证配置也使用 INI 配置文件。pnpm 11/12 中,pnpm config 默认位置是全局,项目级切换应显式传入 --location=project。:contentReference[oaicite:7]{index=7}
恢复项目继承的上级配置:
npm config delete registry --location=project
npm config get registry预期输出
https://registry.npmjs.org/使用 pnpm 时,对应命令为 pnpm config delete registry --location=project。若用户级仍配置了镜像,删除项目项后会显示用户级源,而不一定是 npm 官方源。
全局与项目级选择
--location=project:只影响当前项目,适合仓库固定镜像或私有源。--location=user:影响当前用户的所有项目,适合个人开发机统一加速。--location=global:修改全局配置文件;通常无需为普通项目使用。- pnpm 项目级 registry 会写入工作区根目录
.npmrc,其他非 registry 设置可能写入pnpm-workspace.yaml。:contentReference[oaicite:8]{index=8}
风险与边界
镜像同步延迟或不支持某个作用域时,可能出现旧版本、404 或完整性校验失败。安全替代方案是保留公共默认源,只为企业作用域设置专用地址,例如 @company:registry=https://registry.company.example/。
不要把 _authToken、密码或证书私钥提交到共享 .npmrc。泄露后他人可能下载私有包或冒用发布权限;应把凭据放在用户级安全配置或 CI 密钥中,并让 token 只绑定到目标 registry。:contentReference[oaicite:9]{index=9}
从自定义源生成的锁文件可能保留该源的下载地址,切回 registry 后仍可能继续访问旧地址。先检查锁文件中的 resolved 或 tarball 地址,再在确认依赖版本不变后重新生成锁文件。:contentReference[oaicite:10]{index=10}
排障清单
- 配置未生效:分别执行
npm config get registry、npm config get registry --location=project,检查项目.npmrc是否被用户配置或命令行参数覆盖。 - 返回
401或403:registry 可达但认证失败,检查 token 是否绑定到正确主机和作用域。 - 返回
404:确认包名、版本、作用域映射以及镜像是否已同步。 - TLS 报错:安装企业 CA 或配置正确的
cafile;不要用strict-ssl=false长期绕过证书校验。 - 仍访问旧源:搜索锁文件中的旧域名,并检查代理、CI 缓存和用户级
.npmrc。
速查:团队仓库优先项目级配置,个人开发机才考虑用户级配置;切换后必须读取配置并做一次实际安装验证。
依赖安装
pnpm install [--frozen-lockfile]; npm install根据 package.json 和锁文件安装当前项目的全部依赖。
安装项目依赖
用于首次拉取项目、切换分支或删除 node_modules 后恢复全部依赖。优先按仓库已有锁文件选择管理器:pnpm-lock.yaml 使用 pnpm,package-lock.json 或 npm-shrinkwrap.json 使用 npm,不要在同一分支混用。
基本语法
在包含 package.json 的项目根目录执行:
- npm:
npm install,可缩写为npm i。 - pnpm:
pnpm install,可缩写为pnpm i。
npm install 会读取锁文件;当锁文件与 package.json 不一致时,可能重新解析依赖并更新锁文件。pnpm install 默认安装项目的全部依赖,在工作区根目录执行时还可能安装所有工作区项目的依赖。:contentReference[oaicite:0]{index=0}
高频用法
下面的脚本根据锁文件选择正确的管理器,适合 POSIX Shell:
set -eu
if [ -f pnpm-lock.yaml ]; then
pnpm install
elif [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
npm install
else
echo "未找到 pnpm 或 npm 锁文件,请确认项目使用的包管理器" >&2
exit 1
fi预期输出
# 使用 pnpm 时可能看到
Packages: +<COUNT>
Progress: resolved <COUNT>, reused <COUNT>, downloaded <COUNT>, added <COUNT>, done
# 使用 npm 时可能看到
added <COUNT> packages, and audited <COUNT> packages in <TIME>实际只会出现所选管理器对应的一组输出;依赖数量、缓存命中数和耗时会随项目及网络变化。命令退出码为 0 表示安装完成。
只安装运行时依赖时,pnpm 使用 pnpm install --prod,npm 使用 npm install --omit=dev。这适合已经完成构建的生产镜像,不适合仍需 TypeScript、打包器或测试工具的构建阶段。
需要禁止生命周期脚本时,两者均可追加 --ignore-scripts。该选项适合临时审计不可信依赖,但可能导致原生模块、浏览器驱动或二进制文件未完成初始化。
pnpm 已提前缓存全部包时可使用 pnpm install --offline;只要任一依赖不在本地 store 中,安装就会失败。:contentReference[oaicite:1]{index=1}
风险与边界
混用 npm 和 pnpm 可能同时产生多种锁文件,并形成不同的 node_modules 布局,导致本地正常而 CI 失败。安全做法是保留一种锁文件,并在 package.json 的 packageManager 字段中固定管理器及版本。
普通安装允许锁文件发生变化。触发条件通常是修改了 package.json、切换到锁文件较旧的分支或升级包管理器;后果是产生未审查的依赖变更。安装后应检查 git diff -- package.json package-lock.json pnpm-lock.yaml,确认变化符合预期再提交。
不要为解决安装失败直接使用 --force。它可能重建依赖目录或锁文件,掩盖版本冲突;应先删除错误生成的锁文件、确认 Node.js 与包管理器版本,再在独立分支重新解析依赖。
排障清单
- 出现
package.json找不到:确认当前目录,可执行pwd和ls定位项目根目录。 - 出现锁文件冲突:保留仓库指定的锁文件,删除误生成的另一种锁文件后重新安装。
- 出现注册表超时:检查代理、DNS、私有 registry 地址及认证令牌,不要反复删除锁文件。
- 安装成功但命令不存在:确认对应包是否位于
devDependencies,以及是否错误使用了生产依赖模式。 - 原生模块构建失败:核对 Node.js ABI、操作系统编译工具和生命周期脚本是否被禁用。
速查:日常开发使用普通安装;看到锁文件发生意外变化时先停止提交并检查差异。
pnpm install --frozen-lockfile; npm ci在持续集成环境中严格按照锁文件安装依赖并阻止隐式变更。
执行可复现安装
用于持续集成、自动化测试和部署构建,严格按已提交的锁文件安装依赖。锁文件缺失或与 package.json 不一致时应立即失败,而不是在流水线中隐式修改依赖树。
基本语法
npm 项目使用:npm ci。pnpm 项目使用:
pnpm install --frozen-lockfile
npm ci 要求存在 package-lock.json 或 npm-shrinkwrap.json,会在安装前清理已有 node_modules,锁文件不匹配时退出,并且不会写入清单或锁文件。pnpm 的 --frozen-lockfile 不生成或更新锁文件,缺少锁文件或内容不同步时安装失败。:contentReference[oaicite:2]{index=2}
高频用法
以下脚本可直接用于 CI 的安装步骤,并在安装后验证依赖清单没有被修改:
set -eu
if [ -f pnpm-lock.yaml ]; then
pnpm install --frozen-lockfile
elif [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
npm ci
else
echo "缺少受支持的锁文件,拒绝执行不可复现安装" >&2
exit 1
fi
# 无差异时不输出内容,并以状态码 0 结束
git diff --exit-code -- package.json package-lock.json pnpm-lock.yaml预期输出
# pnpm 分支可能看到
Lockfile is up to date, resolution step is skipped
Packages: +<COUNT>
Done in <TIME>
# npm 分支可能看到
added <COUNT> packages, and audited <COUNT> packages in <TIME>实际只显示其中一个分支。最后的 git diff --exit-code 正常情况下没有输出;若相关文件发生变化,它会返回非零状态并使流水线失败。
只部署运行时依赖时,可使用 pnpm install --frozen-lockfile --prod;npm 通常先执行完整的 npm ci 完成构建,再通过多阶段镜像或 npm prune --omit=dev 生成运行目录。不要在需要编译工具的阶段提前排除开发依赖。
失败结果说明
pnpm 出现 ERR_PNPM_OUTDATED_LOCKFILE 一类错误,通常表示 package.json 已变更但 pnpm-lock.yaml 未同步。应在开发环境运行普通 pnpm install,审查并提交更新后的锁文件,再重新触发 CI。
npm 报告锁文件与清单不一致时,不应在流水线中改用 npm install 绕过。正确处理方式是在本地使用同版本 npm 更新 package-lock.json,完成代码审查后提交。
如果生成 npm 锁文件时使用了会改变依赖树形态的配置,例如 legacy-peer-deps 或 install-links,执行 npm ci 时也必须保持相同配置。较安全的做法是将配置写入项目级 .npmrc 并随仓库提交。:contentReference[oaicite:3]{index=3}
风险与边界
在 CI 中先运行普通安装再运行冻结安装,会让普通安装提前修复锁文件,从而掩盖仓库中的不一致。流水线应直接执行严格安装,并在失败后回到开发分支修复锁文件。
缓存整个 node_modules 可能把旧平台、旧 Node.js ABI 或旧安装参数带入任务。更稳妥的方案是缓存 npm 下载缓存或 pnpm store,每次仍按锁文件重新创建项目依赖目录。
--ignore-scripts 只能阻止脚本执行,不能替代冻结锁文件。触发后依赖版本仍可能正确,但需要安装脚本生成的二进制文件可能缺失;应仅在安全审计阶段使用,并通过构建和测试验证结果。
排障清单
- 确认锁文件已经提交,而不是仅存在于开发者本机。
- 固定 Node.js 和 npm/pnpm 版本,避免不同版本解释锁文件的方式不一致。
- 检查私有 registry 凭证是否在安装步骤之前注入。
- 清理流水线中先于严格安装执行的
npm install或普通pnpm install。 - 原生依赖异常时,核对 CI 与生产环境的操作系统、CPU 架构和 Node.js 主版本。
- 锁文件确需更新时,在本地生成并审查差异,禁止由 CI 自动提交。
pnpm 在识别出的 CI 环境中,只要锁文件存在,默认会启用冻结锁文件行为;显式写出 --frozen-lockfile 仍更便于审查,也能避免脚本移到非 CI 环境后行为改变。:contentReference[oaicite:4]{index=4}
pnpm install --prod --frozen-lockfile; npm ci --omit=dev部署应用时跳过 devDependencies,减少安装体积和攻击面。
只安装生产依赖
用于部署、制作运行镜像或发布制品时跳过 devDependencies。应优先依据锁文件安装,保证生产环境与已验证版本一致;pnpm 与 npm 任选其一,不要在同一项目中混用锁文件。
基本语法
pnpm 项目在包含 pnpm-lock.yaml 的目录执行:
pnpm install --prod --frozen-lockfile预期输出:
Lockfile is up to date, resolution step is skipped
Packages: +<COUNT>
Done in <TIME><COUNT> 和 <TIME> 会随项目与缓存状态变化。命令只安装 dependencies,并在锁文件与 package.json 不一致时直接失败。
npm 项目在包含 package-lock.json 的目录执行:
npm ci --omit=dev预期输出:
added <COUNT> packages, and audited <COUNT> packages in <TIME>
found 0 vulnerabilitiesnpm ci 会先移除现有 node_modules,再严格按锁文件重建依赖;若没有可用锁文件,应先在构建阶段生成并提交锁文件。
高频用法
- 容器构建:先复制
package.json与锁文件,再执行生产安装,最后复制应用代码,以便复用依赖层缓存。 - 已完成编译的 Node.js 服务:仅把运行目录、锁文件和生产依赖放入最终镜像,不把测试工具、TypeScript 编译器或源码映射工具带入运行层。
- 验证安装结果:检查目标运行包是否存在,并确认只用于开发的命令未被依赖。
node -p "require('./package.json').dependencies"预期输出:
{ '<PACKAGE>': '<VERSION_RANGE>', ... }这里读取的是声明在 dependencies 中的运行时依赖;实际键名和版本范围以项目为准。
风险与边界
当应用在启动时仍调用 TypeScript 编译器、测试运行器、代码生成器或仅声明在 devDependencies 的包时,生产安装会导致 MODULE_NOT_FOUND、命令不存在或启动失败。安全替代方案是先在构建阶段产出可运行制品,或把确实在运行期需要的包移动到 dependencies,不要简单取消生产安装。
--frozen-lockfile 和 npm ci 会在清单与锁文件不一致时失败。这是防止线上静默升级的保护;应在提交前更新锁文件,而不是在部署脚本中删除严格校验。
安装脚本仍可能执行依赖包的生命周期脚本。对来源不明的包先审计版本与发布者;需要禁用脚本时可采用受控构建流程,但要确认原生模块不会因此缺少编译产物。
排障清单
- 出现锁文件错误:在开发环境用对应包管理器重新安装并提交更新后的锁文件。
- 启动时报缺包:确认该包是否被错误放在
devDependencies,并检查运行入口是否仍依赖构建工具。 - 容器体积仍很大:检查是否把完整源码、缓存目录或构建层的
node_modules一并复制进最终镜像。 - npm 与 pnpm 结果不一致:确认项目只保留并使用一种锁文件,清理旧
node_modules后重新安装。
速查:pnpm 使用 pnpm install --prod --frozen-lockfile;npm 使用 npm ci --omit=dev。
pnpm add <package>[@<version>]...; npm install <package>[@<version>]...安装应用运行所需的包并写入 dependencies。
添加运行时依赖
当应用代码在启动或处理请求时需要某个包,使用 pnpm add 或 npm install 将其安装并写入 package.json 的 dependencies。以下以 axios 为例,两个包管理器任选其一。
基本语法
pnpm:
pnpm add axios预期输出:
dependencies:
+ axios <VERSION>
Packages: +<COUNT>
Done in <TIME>npm:
npm install axios预期输出:
added <COUNT> packages, and audited <COUNT> packages in <TIME>
found 0 vulnerabilities版本号、包数量和耗时会随仓库状态变化。两条命令都会更新 package.json 与各自锁文件;默认写入 dependencies,不需要额外使用 --save。
常用参数
--save-exact:写入精确版本,例如1.7.9,适合需要严格控制升级的服务。@<VERSION>:安装指定版本,例如axios@1.7.9;版本必须真实存在。--save-dev:写入devDependencies,只适用于测试、构建、格式化等开发工具,不用于运行时依赖。
指定精确版本并验证清单:
pnpm add axios@1.7.9 --save-exact
node -p "require('./package.json').dependencies.axios"预期输出:
1.7.9npm 项目可把第一行替换为 npm install axios@1.7.9 --save-exact,验证命令不变。
高频用法
- 新增 HTTP 客户端、数据库驱动、日志库等运行期模块:直接添加到
dependencies。 - 修复缺失依赖:先确认源码确实直接导入该包,再添加;不要靠其他包的传递依赖“顺带提供”。
- 升级现有依赖:指定经过验证的版本,并同时提交
package.json和锁文件,避免部署环境解析出不同结果。 - 单仓多包项目:在目标包目录执行命令,避免把业务依赖误写到仓库根清单。
风险与边界
安装未知包或错误拼写的近似包名时,可能执行恶意生命周期脚本并污染构建环境。安全替代方案是先核对官方包名、发布者、仓库地址与最近版本,再在隔离环境安装并审查锁文件变化。
把构建工具误装到 dependencies 会增加生产体积和攻击面;把运行库误装到 devDependencies 则会在生产安装时缺失。判断标准是“应用运行时是否直接需要”,而不是“开发时是否使用”。
不要交替使用 npm 与 pnpm 安装同一项目。混用会生成不同锁文件、不同依赖布局,并可能让本地与 CI 的解析结果不一致;应保留项目约定的包管理器和锁文件。
排障清单
- 报
No matching version found:检查包名和版本是否存在,移除错误的版本约束后重试。 - 报权限或网络错误:先检查代理、私有仓库登录状态和 registry 配置,不要直接使用管理员权限绕过。
- 安装成功但运行时报缺包:确认命令是在正确工作区执行,并检查依赖是否写入当前应用的
package.json。 - 锁文件出现大范围变化:确认包管理器版本和 registry 是否一致,避免无意中重算整个依赖树。
速查:运行库默认用 pnpm add <PACKAGE> 或 npm install <PACKAGE>;只有开发工具才使用 --save-dev。
pnpm add --save-dev <package>...; npm install --save-dev <package>...安装测试、构建和代码检查工具并写入 devDependencies。
添加开发依赖
用于安装测试、构建、类型检查和代码规范工具,并把包写入 package.json 的 devDependencies。npm 使用 install -D,pnpm 使用 add -D;两者都会更新各自的锁文件。:contentReference[oaicite:0]{index=0}
命令定位
适合 ESLint、TypeScript、Vitest、Vite、Webpack 等只在开发、测试或构建阶段使用的包。应用运行时会直接 import 或 require 的库通常应放入 dependencies,不要为了“统一”全部使用 -D。
高频用法
npm 项目安装多个开发工具:
npm install --save-dev eslint typescript预期输出:
added <COUNT> packages, and audited <COUNT> packages in <TIME><COUNT>、<TIME> 以及审计提示随缓存、平台和已有依赖变化;安装完成后应出现 package-lock.json 变更。pnpm 项目执行等价操作:
pnpm add --save-dev eslint typescript预期输出:
devDependencies:
+ eslint <VERSION>
+ typescript <VERSION>
Done in <TIME>实际版本与耗时可能不同;安装完成后应出现 pnpm-lock.yaml 变更。核对清单位置,不依赖安装日志判断:
node -p "JSON.stringify(require('./package.json').devDependencies, null, 2)"预期输出:
{
"eslint": "^<VERSION>",
"typescript": "^<VERSION>"
}版本前缀由包管理器配置决定,可能是 ^、~ 或精确版本。
常用参数
-D、--save-dev:写入devDependencies。-E、--save-exact:保存精确版本,例如eslint: "9.39.1",而不是版本范围。--ignore-scripts:安装时不执行依赖的生命周期脚本,适合先审查不可信包;依赖原生编译或生成步骤的工具可能因此不可用。- pnpm 工作区根目录只有在确实要给根包添加工具时才使用
-w;通常应进入目标子包,或配合--filter指定包。
风险与边界
当部署环境在安装前设置 NODE_ENV=production、使用 npm 的 --omit=dev,或使用 pnpm 的仅生产依赖安装方式时,开发依赖不会完整落盘。若构建流程仍需要 TypeScript、Vite 等工具,会出现“command not found”或模块缺失。安全做法是先安装完整依赖并构建,再在运行镜像中仅保留生产依赖,或采用多阶段构建。
安装来源不可信的包时,其 preinstall、install、postinstall 脚本可能执行本机命令。先核对包名、发布者和版本;需要隔离审查时使用 --ignore-scripts,确认后再正常安装。不要在同一项目混用 npm 与 pnpm,否则多个锁文件可能导致本地、CI 和生产解析出不同依赖树。
排障清单
package.json没有变化:确认当前目录存在目标项目的package.json,并检查是否误用了--no-save。- pnpm 报工作区根目录检查错误:进入具体子包;只有根包确实需要该工具时才执行
pnpm add -Dw <包名>。 - CI 找不到构建工具:检查安装阶段是否省略了
devDependencies,以及构建是否发生在裁剪生产依赖之前。 - 安装后命令仍不可用:优先通过项目脚本或
npm exec <命令>、pnpm exec <命令>调用本地二进制,不要依赖全局安装。
pnpm add <package>@<version-or-tag>...; npm install <package>@<version-or-tag>...使用精确版本、版本范围或 dist-tag 安装目标包。
安装指定版本
使用 <包名>@<版本说明> 选择精确版本、SemVer 范围或 dist-tag。精确版本便于稳定复现,范围允许接收兼容更新,dist-tag 适合跟随发布方维护的 latest、next、beta 等通道。npm 与 pnpm 都支持这些形式,并可用 -E 保存精确版本。:contentReference[oaicite:1]{index=1}
基本语法
npm install <包名>@<精确版本|版本范围|dist-tag>
pnpm add <包名>@<精确版本|版本范围|dist-tag>这是语法模板,尖括号内容需要替换;不要把尖括号原样输入终端。
高频用法
安装并保存精确版本,适合修复回归、复现线上环境或锁定构建工具:
npm install lodash@4.17.21 --save-exact
node -p "require('./package.json').dependencies.lodash"
node -p "require('lodash/package.json').version"预期输出:
4.17.21
4.17.21第一行是清单声明,第二行是实际安装版本;两者一致表示已精确固定。安装版本范围,允许后续解析同一主版本内的兼容更新:
pnpm add "lodash@^4.17.20"
node -p "require('./package.json').dependencies.lodash"
node -p "require('lodash/package.json').version"预期输出:
^4.17.20
<RESOLVED_VERSION><RESOLVED_VERSION> 是满足 >=4.17.20 <5.0.0 的实际版本;准确值以锁文件和第二条命令为准。给范围加引号,可减少不同 Shell 对特殊字符的解释差异。按 dist-tag 安装发布方当前标记的版本:
npm install lodash@latest
node -p "require('lodash/package.json').version"预期输出:
<TAG_TARGET_VERSION><TAG_TARGET_VERSION> 是执行时 latest 指向的版本,同一命令在不同日期可能得到不同结果。
版本选择速查
1.2.3:只接受1.2.3。^1.2.3:通常允许升级次版本和补丁版本,但不跨主版本。~1.2.3:通常只允许升级补丁版本。latest、next、beta:由包发布者维护的可移动标签,不等同于固定版本。-E、--save-exact:要求写入package.json时不自动添加范围符号。
风险与边界
使用范围或 dist-tag 时,只看 package.json 不能证明每台机器安装完全相同;删除锁文件、更新依赖或重新解析标签后,实际版本可能变化并引入行为差异。生产和 CI 应提交锁文件,并使用 npm ci 或 pnpm install --frozen-lockfile 阻止静默改锁。
精确固定版本能降低意外升级,但也会阻止补丁和安全修复自动进入。安全替代方案不是长期不升级,而是通过依赖更新流程、自动化测试和变更审查定期提升固定版本。
dist-tag 是可移动指针,next、beta 常指向预发布版本。不要仅凭标签名判断稳定性;先查询并记录目标版本,再在生产变更中改成精确版本。
排障清单
- 报
No matching version found:用npm view <包名> versions --json或pnpm view <包名> versions --json确认版本是否发布、仓库配置是否正确。 - 声明版本与实际版本不一致:检查锁文件、工作区覆盖项、
overrides、resolutions或缓存后的依赖树。 - 修改版本后仍加载旧代码:删除应用构建缓存并重新构建;不要先删除锁文件,除非确实要重新解析整棵依赖树。
- CI 拒绝安装:若使用冻结锁文件模式,应先在本地用同一包管理器更新清单和锁文件,再一起提交。
pnpm add --global <package>[@<version>]...; npm install --global <package>[@<version>]...全局安装命令行工具并排查全局可执行文件路径问题。
安装全局工具
用于把 typescript、eslint、prettier 等命令行工具安装到全局目录,并确认生成的可执行文件已经进入 PATH。团队项目优先使用项目内依赖;全局安装更适合个人通用工具或临时运维命令。
基本语法
pnpm add -g <package>[@<version>]
npm install -g <package>[@<version>]-g 或 --global 表示全局安装;省略版本时通常解析当前默认标签,生产环境建议固定主版本或完整版本,避免新版本改变命令行为。
高频用法
使用 pnpm 安装 TypeScript,并同时验证全局目录、命令路径和版本:
pnpm add -g typescript
pnpm bin -g
command -v tsc
tsc --version预期输出
Packages: +<N>
Done in <TIME>
<PATH>
<PATH>/tsc
Version <VERSION><PATH>、<TIME> 和 <VERSION> 随系统与安装版本变化。只要 command -v tsc 返回的路径位于 pnpm bin -g 输出目录中,且版本命令成功,即表示安装与 PATH 均正常。
使用 npm 时可执行:
npm install -g typescript
npm prefix -g
command -v tsc
tsc --version预期输出
added <N> package(s) in <TIME>
<PATH>
<PATH>/tsc
Version <VERSION>npm prefix -g 返回全局前缀;在常见类 Unix 环境中,可执行文件通常位于该前缀的 bin 目录。Windows 请用 where.exe tsc 或 PowerShell 的 Get-Command tsc 定位命令。
安装固定版本或升级指定工具:
pnpm add -g typescript@5.9.2
npm install -g typescript@5.9.2预期输出
安装完成;tsc --version 输出 Version 5.9.2风险与边界
全局版本不会写入项目的 package.json 和锁文件。触发条件是构建、测试或代码生成依赖全局工具;后果是开发机与 CI 使用不同版本。安全替代方案是在项目中执行 pnpm add -D <package> 或 npm install -D <package>,再通过 pnpm exec <command>、npm exec <command> 或项目脚本运行。
不要为解决权限错误直接使用 sudo npm install -g。当 Node/npm 安装目录归系统用户所有时,sudo 可能生成 root 所有的缓存与全局文件,后续普通用户安装或升级会持续报权限错误。优先使用 Node 版本管理器,或把 npm 的用户级 prefix 配置到当前用户可写目录。
全局包可能执行安装脚本。安装来源不可信或脚本权限过大时,可能执行任意本机命令。先核对包名、发布者与版本;pnpm 新版可按需使用 --allow-build=<package> 明确批准构建脚本,不要无条件放开所有脚本。
排障清单
command not found:执行pnpm bin -g或npm prefix -g,确认对应可执行目录已加入PATH,然后重开终端。- pnpm 报
ERR_PNPM_NO_GLOBAL_BIN_DIR:执行pnpm setup,重开终端后再次检查pnpm bin -g。pnpm v11 的全局命令位于$PNPM_HOME/bin。:contentReference[oaicite:0]{index=0} - 安装成功但命中旧版本:执行
command -v -a tsc、which -a tsc或where.exe tsc,删除或调整排在前面的旧路径。 - 切换 Node 版本后工具消失:版本管理器通常为不同 Node 版本维护独立全局目录,需要在当前版本重新安装,或改用项目内依赖。
pnpm 使用 pnpm add -g <pkg> 管理全局包;pnpm install -g 不带包名不受支持。npm 则通过全局前缀放置包和命令。:contentReference[oaicite:1]{index=1}
依赖维护
pnpm remove <package>...; npm uninstall <package>...删除已安装的包并同步更新 package.json 与锁文件。
移除依赖
用于从当前项目删除直接依赖,并同步修改 package.json、锁文件与 node_modules。应在包含目标依赖声明的项目或工作区包目录执行,不要只手工删除 node_modules 下的文件。
基本语法
pnpm remove <package>
npm uninstall <package>pnpm 还支持 rm、uninstall、un 别名;npm 常用 uninstall、remove、rm。正常执行时,两者都会删除安装内容,并更新项目依赖声明与各自锁文件。:contentReference[oaicite:2]{index=2}
高频用法
在项目根目录移除直接依赖 lodash,随后验证它已不再声明于 package.json:
pnpm remove lodash
node -e "const p=require('./package.json'); console.log(Boolean(p.dependencies?.lodash || p.devDependencies?.lodash || p.optionalDependencies?.lodash))"预期输出
Packages: -<N>
Done in <TIME>
falsefalse 表示当前包已不再直接声明 lodash。如果 node_modules 中仍能找到它,通常是其他依赖仍将它作为传递依赖使用,不代表移除失败。使用 npm 时执行:
npm uninstall lodash
node -e "const p=require('./package.json'); console.log(Boolean(p.dependencies?.lodash || p.devDependencies?.lodash || p.optionalDependencies?.lodash))"预期输出
removed <N> package(s), and audited <N> package(s) in <TIME>
false在 pnpm 工作区中,只从指定包移除依赖:
pnpm --filter @acme/web remove lodash预期输出
@acme/web 的 package.json 与锁文件已更新,其他工作区包保持不变npm 工作区可使用 npm uninstall lodash -w @acme/web。执行前先确认工作区名称与 package.json 中的 name 一致。移除全局工具:
pnpm remove -g typescript
npm uninstall -g typescript预期输出
全局安装记录已删除;再次执行 tsc --version 应提示命令不存在,除非 PATH 中还有另一份 tsc风险与边界
不要直接执行 rm -rf node_modules/<package> 代替卸载。触发条件是只删除物理目录;后果是 package.json 与锁文件仍声明该包,下一次安装会恢复它,并造成环境状态难以复现。安全替代方案是使用 pnpm remove 或 npm uninstall,然后提交清单与锁文件变更。
谨慎使用 pnpm remove -r <package>。在工作区根目录执行时会尝试从多个包移除同名依赖,可能破坏仍需该依赖的应用。安全替代方案是先用 pnpm --filter <package-name> remove <dependency> 精确限定目标,再运行测试。
npm 的 --no-save 会只改变本地安装状态而保留 package.json 与锁文件声明。触发条件是执行 npm uninstall <package> --no-save;后果是当前机器暂时缺包,但后续 npm install 会重新安装。除临时诊断外不要使用,正常移除应保留默认保存行为。:contentReference[oaicite:3]{index=3}
pnpm v11 支持把逗号分隔的多个全局包安装成同一隔离组;移除其中任意一个会删除整个组。若工具需要独立维护,应使用空格分开安装,或分别执行全局安装命令。:contentReference[oaicite:4]{index=4}
排障清单
package.json没变化:确认当前目录确实是声明该依赖的包;在工作区中使用pnpm --filter或 npm 的-w指定包。- 删除后代码仍能导入:执行
pnpm why <package>或npm explain <package>,检查是否仍被其他直接依赖间接引入。 - 锁文件冲突:不要手工删冲突段;先保留正确的
package.json,再用项目约定的包管理器重新安装并运行测试。 - CI 仍安装旧包:确认修改后的
package.json与pnpm-lock.yaml或package-lock.json已一起提交,且 CI 没有恢复旧缓存或旧工作区。
速查:删除直接依赖用 remove/uninstall,删除某个工作区包中的依赖要加精确过滤条件,删除全局工具才使用 -g。
pnpm update <package>... [--latest]; npm update [<package>...]在版本范围内或跨版本范围升级指定依赖。
更新单个依赖
用于只升级一个已声明的依赖。先区分“仍在 package.json 版本范围内更新”和“跨出当前范围更新”,再检查依赖清单、锁文件与测试结果。
命令定位
pnpm update <包名> 与 npm update <包名> 会在当前声明允许的语义化版本范围内选择可用版本。需要升级到注册表 latest 标签指向的版本时,pnpm 使用 --latest;npm 通常使用 npm install <包名>@latest,同时更新依赖声明和锁文件。
只在项目根目录或目标 workspace 中执行。仓库已经固定包管理器时,不要交叉运行 pnpm 与 npm,否则可能同时产生 pnpm-lock.yaml 和 package-lock.json。
高频用法
pnpm:在现有范围内更新
下面假设项目已经直接依赖 lodash。命令会更新安装结果和 pnpm-lock.yaml;如果原声明仍能覆盖新版本,package.json 中的范围通常无需改变。
pnpm update lodash
pnpm list lodash --depth 0预期输出
dependencies:
lodash <INSTALLED_VERSION>读取方法:<INSTALLED_VERSION> 是更新后的实际版本。若提示 Already up to date,表示当前锁定版本已是声明范围内可选的最高版本。
npm:在现有范围内更新
npm update lodash
npm ls lodash --depth=0预期输出
<PROJECT>@<VERSION> <PATH>
└── lodash@<INSTALLED_VERSION>读取方法:最后一行是根项目直接安装的版本;命令仍受 package.json 中 ^、~ 或精确版本约束。
跨版本范围更新
pnpm 用 --latest,npm 用显式的 @latest。这类操作会改变依赖声明,可能跨主版本。
pnpm update lodash --latest
pnpm list lodash --depth 0预期输出
dependencies:
lodash <LATEST_VERSION>npm 项目使用:
npm install lodash@latest
npm ls lodash --depth=0预期输出
<PROJECT>@<VERSION> <PATH>
└── lodash@<LATEST_VERSION>实际版本由执行时的注册表标签决定,因此 <LATEST_VERSION> 可能不同。
常用参数
- pnpm
--latest或-L:忽略原版本范围,升级到latest稳定标签。 - pnpm
--interactive或-i:交互选择要更新的依赖,适合一次审查少量包。 - pnpm
--dev、--prod:仅处理开发依赖,或仅处理生产与可选依赖。 - npm
--dry-run:只预演依赖树变化,不写入磁盘,适合先确认影响。 - workspace 仓库中,pnpm 可配合
-r、--filter,npm 可配合--workspace限定目标包。
风险与边界
跨主版本、跨 0.x 次版本或更换预发布标签时,可能出现 API 删除、配置格式变化、类型错误或运行时行为改变。安全做法是在独立分支执行,阅读变更记录,运行单元测试、构建和关键链路回归后再合并。
更新会重算锁文件,并可能执行依赖的安装脚本。对来源不明的包或生产紧急变更,应先在隔离环境审查包来源、发布者和脚本,再更新;不要直接在生产目录覆盖安装。
排障清单
- 版本未变化:先运行过期检查,确认是否存在满足当前范围的更高版本;需要跨范围时显式使用
--latest或@latest。 - 更新了错误的 workspace:确认当前目录,或显式使用
--filter、--workspace。 - CI 使用旧版本:确认锁文件已提交,并检查 CI 是否启用了冻结锁文件安装。
- 测试失败:回退
package.json与锁文件到同一提交,不要只手工修改node_modules。
速查:范围内升级优先使用 update;跨范围升级必须显式指定,并把测试与锁文件差异一起审查。
pnpm outdated [<package>...]; npm outdated [<package>...]比较当前版本、允许版本和最新版本,制定依赖升级计划。
检查过期依赖
用于比较当前安装版本、声明范围内可升级版本与注册表最新版本。先识别“可直接升级”和“需要评估兼容性”的依赖,再制定分批升级计划。
基本语法
pnpm 使用 pnpm outdated [包名或模式],npm 使用 npm outdated [包名]。不带包名时检查当前项目的直接依赖;需要查看传递依赖时,npm 增加 --all,pnpm 在 workspace 中可使用 -r 或 --filter 扩大检查范围。
高频用法
pnpm:查看全部过期依赖
pnpm outdated预期输出
┌─────────┬─────────┬─────────┐
│ Package │ Current │ Latest │
├─────────┼─────────┼─────────┤
│ lodash │ 4.17.20 │ 4.17.21 │
└─────────┴─────────┴─────────┘Current 是当前安装或锁定版本,Latest 是注册表 latest 标签对应版本。实际项目可能额外显示依赖类型、使用方或详情列。只想查看当前声明范围内可兼容升级的版本时:
pnpm outdated --compatible预期输出
┌─────────┬─────────┬─────────┐
│ Package │ Current │ Latest │
├─────────┼─────────┼─────────┤
│ lodash │ 4.17.20 │ 4.17.21 │
└─────────┴─────────┴─────────┘若没有输出,表示没有符合当前 package.json 约束的过期依赖;这不代表不存在跨范围的新版本。
npm:同时读取 Current、Wanted、Latest
npm outdated预期输出
Package Current Wanted Latest Location Depended by
lodash 4.17.20 4.17.21 4.17.21 node_modules/lodash <PROJECT>Current 是已安装版本;Wanted 是满足当前声明范围的最高可用版本;Latest 是注册表 latest 标签版本。Wanted 高于 Current 时通常可先做范围内升级;Latest 高于 Wanted 时说明需要修改版本范围并评估兼容性。
只检查指定依赖
pnpm outdated lodash
npm outdated lodash预期输出
仅显示 lodash;若没有输出,表示该包在本次检查条件下没有可报告的更新。常用参数
- pnpm
--long:增加依赖使用方和详情,适合 workspace 定位影响面。 - pnpm
--format table|list|json:切换人读或脚本处理格式。 - pnpm
--dev、--prod、--no-optional:按依赖类型缩小结果。 - npm
--all:把传递依赖也纳入检查,结果可能明显增多。 - npm
--long:显示依赖类型、主页和使用方等信息。 - npm
--json:输出机器可读结果,适合 CI 生成报告。
制定升级计划
优先处理当前版本低于允许版本的依赖,这类更新通常不需要修改版本范围,但仍应执行测试。对于最新版本超出允许范围的依赖,按主版本、核心运行时依赖、构建工具和类型包分组,逐组阅读变更记录并升级,避免一次更新全部依赖导致故障难以定位。
安全相关更新不能只看 Latest。还应结合审计结果、修复版本说明和项目实际调用路径判断优先级;“版本最新”不等于“当前项目风险最低”。
风险与边界
过期检查依赖当前注册表、镜像同步状态和 dist-tag 配置。使用企业镜像或私有源时,结果可能落后于公共注册表;安全替代方案是先确认 npm config get registry 或 pnpm config get registry 指向预期源,再比较结果。
Git、文件路径、workspace 链接和预发布依赖不一定能按普通语义化版本解释。遇到 git、linked 或标签值时,应检查依赖声明本身,不要直接把输出当成可自动升级的版本号。
排障清单
- 没有任何输出:可能全部已是最新,也可能当前目录不是目标项目;先确认存在
package.json和对应锁文件。 Wanted与预期不符:检查package.json的^、~、精确版本、overrides 或 workspace 约束。- pnpm 与 npm 结果不同:确认二者读取的是同一注册表、同一项目和同一锁文件策略。
- CI 把过期依赖当失败:检查脚本是否正确处理命令退出状态,并将“发现更新”和“命令执行错误”分开记录。
速查:npm 重点比较 Current → Wanted → Latest;pnpm 用默认结果看最新版本,用 --compatible 单独筛选当前范围内可升级项。
脚本与命令执行
pnpm run [<script> [<args>...]]; npm run [<script> [-- <args>...]]执行 package.json 中定义的开发、测试、构建和发布脚本。
运行项目脚本
在项目根目录执行 package.json 的 scripts。开发、测试、构建等动作应写进脚本,团队和 CI 再通过 npm 或 pnpm 使用同一入口,避免每个人手工拼接不同命令。
基本语法
npm 使用 npm run <脚本名>,pnpm 使用 pnpm run <脚本名>。pnpm 对不与内置命令重名的脚本还支持 pnpm <脚本名>,但自动化脚本建议保留 run,意图更明确。
下面的最小 package.json 可直接保存后运行:
{
"name": "script-demo",
"version": "1.0.0",
"private": true,
"scripts": {
"dev": "node -e \"console.log('dev server started')\"",
"test": "node -e \"console.log('tests passed')\"",
"build": "node -e \"console.log('build completed')\""
}
}配置生效后,分别执行构建和测试:
npm run build
pnpm run test预期输出(npm、pnpm 的脚本标题和项目路径可能不同,末行结果应一致):
> script-demo@1.0.0 build
> node -e "console.log('build completed')"
build completed
> script-demo@1.0.0 test <PATH>
> node -e "console.log('tests passed')"
tests passed高频用法
不带脚本名执行 npm run 或 pnpm run,用于列出当前包可运行的脚本。运行开发、测试和构建通常分别使用 npm run dev、npm test、npm run build,pnpm 对应写成 pnpm run dev、pnpm test、pnpm run build。
向脚本传递以短横线开头的参数时,npm 使用 npm run test -- --watch;-- 后内容交给目标脚本。pnpm 可用 pnpm run test --watch,因为脚本名后的参数会直接转发;pnpm 自身的选项应放在脚本名前。
工作区中,npm 可用 npm run build --workspace=<PACKAGE> 或 npm run build --workspaces。pnpm 常用 pnpm --filter <PACKAGE> run build,批量执行则用 pnpm -r run build。
风险与边界
脚本本质上是当前用户权限下的 Shell 命令。触发条件是运行来自未知仓库、未审查分支或被篡改的 package.json;后果可能包括删除文件、上传环境变量或改写制品。安全做法是先检查 scripts、锁文件和代码差异,在普通用户、隔离容器或受限 CI 中执行,不要携带生产密钥。
pre<脚本名> 和 post<脚本名> 可能自动随主脚本执行。只检查 build 而忽略 prebuild、postbuild,可能漏掉额外发布或清理动作;执行前应一并审查。--if-present 会忽略脚本不存在的问题,适合可选任务,不适合必须执行的测试或发布门禁。
排障清单
Missing script或ERR_PNPM_NO_SCRIPT:确认当前目录对应正确的package.json,并核对脚本名大小写。command not found:先按锁文件安装依赖;脚本会自动把本地node_modules/.bin加入PATH。- 参数未生效:npm 检查是否漏写参数分隔符
--;pnpm 检查自身选项是否误放到脚本名之后。 - Windows 与 Linux 结果不同:脚本可能依赖
rm、export等 POSIX 语法,改用跨平台 Node 脚本或显式配置兼容 Shell。 - CI 卡住或日志混乱:检查脚本是否启动常驻服务、等待交互输入,或在工作区并发运行了过多任务。
速查:先用 npm run 或 pnpm run 确认入口,再运行目标脚本;生产和 CI 中优先使用明确脚本名、锁定依赖并检查退出码。
pnpm dlx <package>[@<version>] [<args>...]; npm exec [--yes] --package=<package> -- <command> [<args>...]使用 npm exec、npx 或 pnpm dlx 运行未永久安装的命令行工具。
临时执行包命令
需要偶尔运行脚手架、检查器或迁移工具,但不想把它永久写入 dependencies 或 devDependencies 时,使用 npm exec、npx 或 pnpm dlx。工具仍可能被下载到缓存,但不会自动成为项目依赖。
基本语法
npm exec 适合显式区分“下载哪个包”和“执行哪个二进制”;npx 是 npm 提供的便捷入口;pnpm dlx 是 pnpm 的一次性执行方式。
npm exec --yes --package=semver@7.8.5 -- semver 1.2.3
npx --yes semver@7.8.5 1.2.3
pnpm dlx semver@7.8.5 1.2.3预期输出:
1.2.3
1.2.3
1.2.3三个命令都临时取得固定版本的 semver CLI,并校验输入版本。首次执行需要访问配置的包仓库,耗时和缓存路径因环境而异。
常用参数
npm exec --package=<包>@<版本> -- <命令> <参数> 中,--package 指定要放入临时执行环境的包,第二个 -- 将后续参数交给目标命令。包名与二进制名不一致,或需要同时提供多个包时,应优先使用这种显式形式。
npx --yes <包>@<版本> ... 的 --yes 跳过下载确认;npx 自身选项应放在包名之前。pnpm dlx --package=<包> <命令> 同样可处理包名与命令名不同的情况;确需允许某个包执行构建脚本时,再使用 --allow-build=<包名>,不要对未知包放宽限制。
高频用法
初始化项目时可运行带版本的脚手架,例如 npx --yes create-vite@<VERSION> <PATH> 或 pnpm dlx create-vite@<VERSION> <PATH>。固定版本可避免 latest 在不同日期生成不同结构;<VERSION> 和 <PATH> 替换为实际值。
一次性检查或格式化时,优先固定工具版本并先在干净工作区运行。若工具已写入项目依赖,改用 npm exec -- <命令> 或 pnpm exec <命令>,这样会使用锁文件约束的本地版本,通常比再次远程解析更可复现。
包暴露的命令名不明确时,使用 npm exec --package=<包>@<版本> -- <二进制> --help 或 pnpm dlx --package=<包>@<版本> <二进制> --help,不要反复猜测并执行相似包名。
风险与边界
临时执行会运行第三方代码。触发条件包括拼错包名、使用未固定的 latest、跳过确认或在带生产凭据的终端执行;后果可能是命中仿冒包、执行恶意安装脚本、读取文件和环境变量。安全替代方案是核对包名、发布者和版本,固定精确版本,使用可信仓库,在无管理员权限且不含敏感环境变量的隔离目录运行。
--yes 只关闭交互确认,不代表包可信。CI 中可以使用它避免挂起,但必须同时固定版本并通过依赖审查。一次性执行也不等于无痕:包管理器通常会保留下载缓存,敏感环境应按本机策略清理缓存和临时目录。
排障清单
could not determine executable to run:包未声明唯一可执行文件;改用--package明确包,再写真实二进制名。- 参数被 npm 或 npx 吞掉:将包装器选项放在包名前;
npm exec使用--分隔目标命令。 - 下载超时、证书或鉴权失败:检查 registry、代理、CA 和登录配置,先验证同一仓库能否正常查询包。
Unsupported engine或运行时语法错误:目标包要求的 Node.js 版本与当前环境不兼容,换兼容版本或升级 Node.js。- 本地有工具却仍下载:确认调用的是
npm exec或pnpm exec,并检查当前目录是否属于已安装依赖的项目。
速查:临时工具优先固定精确版本;项目长期使用的工具应加入 devDependencies 并通过锁文件执行,不要长期依赖在线的一次性下载。
npm run <script> -- <args>...; pnpm run <script> [<args>...]向 package scripts 或其调用的底层命令传递额外参数。
传递脚本参数
在需要临时改变测试范围、构建模式、端口或输出目录时,把额外参数传给 package.json 中的目标脚本。npm 需要用 -- 明确结束自身参数;pnpm 会把脚本名之后的参数交给底层命令。
基本语法
npm 的稳定写法是:
npm run <SCRIPT> -- <ARGUMENTS>pnpm 的运行选项应放在脚本名前,脚本参数放在脚本名后:
pnpm run <PNPM_OPTIONS> <SCRIPT> <ARGUMENTS>这里的尖括号是占位符,不要原样输入。例如 npm 中缺少分隔符 -- 时,--mode、--watch 等选项可能被 npm 自己解析;pnpm 中把 --silent 放到脚本名后,则会传给底层命令,而不是控制 pnpm 日志。
主示例
先保存以下两个文件。package.json 只注册脚本,实际参数由 Node 程序读取。
{
"name": "script-args-demo",
"private": true,
"scripts": {
"inspect-args": "node scripts/show-args.mjs"
}
}// scripts/show-args.mjs
const args = process.argv.slice(2);
console.log(JSON.stringify(args));分别使用 npm 和 pnpm 执行;下面两条命令会各运行一次脚本。
npm run inspect-args -- --mode production --port 4173
pnpm run inspect-args --mode production --port 4173预期输出的关键行如下;包管理器额外打印的脚本名称和执行命令可能不同。
["--mode","production","--port","4173"]
["--mode","production","--port","4173"]读取时从左到右按“选项、值”配对:--mode 的值是 production,--port 的值是 4173。
高频用法
测试框架参数可使用 npm test -- --runInBand;pnpm 对应为 pnpm test --runInBand。参数名称必须由实际测试工具支持,包管理器不会校验其含义。
单个工作区执行构建时,npm 使用 npm run build -w <WORKSPACE> -- --mode staging;pnpm 使用 pnpm --filter <WORKSPACE> run build --mode staging。工作区筛选参数必须放在脚本名前,否则可能被错误传给构建工具。
位置参数也可直接传递,例如 npm run release -- 1.4.0 或 pnpm run release 1.4.0。底层脚本应明确校验参数数量和格式,避免把缺失值当成默认发布目标。
风险与边界
-- 只是参数解析边界,不是安全边界。触发条件是把用户输入、分支名或路径直接拼进 shell 命令;后果可能是参数注入、误删文件或发布到错误环境。安全替代方案是在 Node 脚本中读取 process.argv,使用参数解析库校验白名单,并通过 spawn 的参数数组调用子进程,避免字符串拼接。
npm 传入的参数只交给目标脚本,不会自动传给对应的 pre<SCRIPT> 和 post<SCRIPT>。需要三个阶段共享配置时,改用环境变量或显式调用同一个参数解析程序。
跨平台脚本受 shell 影响。触发条件是依赖单引号、变量展开或 Unix 命令;后果是在 Windows 默认 cmd.exe 下失败。安全替代方案是把复杂逻辑移入 .js、.mjs 或跨平台 CLI,并避免在 package.json 中堆叠长 shell 表达式。
排障清单
- 报“未知 npm 选项”:确认 npm 命令在脚本名后包含
--。 - pnpm 日志选项未生效:把
--silent、--filter、--recursive等 pnpm 选项移到脚本名前。 - 底层程序收不到参数:临时打印
process.argv,并确认脚本没有通过另一个包装命令吞掉参数。 - 引号或路径在不同系统失效:检查实际脚本 shell,优先改为参数数组和跨平台 Node 脚本。
速查:npm 使用 npm run <SCRIPT> -- <ARGS>;pnpm 把运行选项放在脚本名前,把脚本参数放在脚本名后。
信息与依赖追踪
npm view <package>[@<version>] [<field>...]; pnpm view <package>[@<version>] [<field>]查询包的版本、标签、依赖、入口、许可证和发布时间等元数据。
查看包信息
在安装、升级或排查依赖前,使用 view 直接查询注册表中的包元数据,可确认当前标签指向的版本、依赖约束、入口文件、许可证和发布时间,而不必先安装该包。
基本语法
npm view <PACKAGE> [FIELD...]
pnpm view <PACKAGE> [FIELD]npm 还支持别名 info、show、v;pnpm 支持 info、show。省略版本时通常读取 latest 标签指向的版本;使用 <PACKAGE>@<VERSION> 可锁定查询对象。字段可使用点号读取子属性,例如 dist-tags.latest、repository.url。
主示例
下面分别用 npm 和 pnpm 查询 express 当前 latest 标签对应的版本。
npm view express version
pnpm view express version预期输出如下,实际版本会随注册表发布而变化。
<VERSION>
<VERSION>两行应是版本号;如果两者不同,先检查是否配置了不同注册表、缓存代理或作用域规则,而不要直接认定其中一个工具解析错误。
高频用法
查看标签时使用 npm view express dist-tags 或 pnpm view express dist-tags。latest 只是维护者设置的标签,不保证等于数值最大的语义化版本;升级脚本应读取目标标签或明确版本,而不是自行猜测。
查看依赖约束时使用 npm view express dependencies;只查单个依赖可用 npm view express dependencies.debug。pnpm 可用 pnpm view express dependencies 查看完整依赖对象。
查看入口时优先检查 exports,再看 main、module、types、typings 和 bin。现代包可能只通过 exports 暴露入口,因此仅看到 main 项缺失并不代表包不可导入。
查看发布时间可使用 npm view express time;查询指定版本时可用 npm view express "time[<VERSION>]"。尖括号应替换为真实版本号,引号用于避免 shell 把方括号解释成通配模式。
结构化输出
自动化脚本可添加 --json,但应先固定 npm 主版本并验证返回结构。
npm view express version --json
pnpm view express version --json预期结果中的版本值会变化;npm 12 的 JSON 输出始终为数组,pnpm 输出结构以所用主版本为准。
[
"<VERSION>"
]
"<VERSION>"读取时不要直接按旧版 npm 的字符串或对象结构解析。生产脚本应先校验顶层类型,再提取版本值;需要长期稳定时,锁定工具版本并加入契约测试。
风险与边界
查询结果来自当前配置的注册表。触发条件是项目 .npmrc、用户配置或作用域配置指向私有镜像;后果是版本、标签、许可证甚至包是否存在都可能与公共注册表不同。安全替代方案是先核对 npm config get registry 或 pnpm config get registry,在 CI 中显式设置可信注册表。
元数据不是安全审计结果。触发条件是仅凭许可证、维护者或更新时间决定是否上线;后果是遗漏恶意版本、供应链劫持或已知漏洞。安全替代方案是结合锁文件、完整性校验、审计工具和内部准入策略,不要把 view 当成安装安全证明。
不要在高频循环中无节制查询注册表。触发条件是脚本逐包逐字段重复请求;后果是被限流、构建变慢或因网络抖动失败。安全替代方案是一次读取所需对象、缓存结果,并为网络请求设置超时与重试上限。
排障清单
- 返回
E404:检查包名、作用域、版本以及当前注册表是否包含该包。 - 返回
E401或E403:检查私有源令牌、权限和作用域对应的 registry 配置。 - 字段为空:先执行不带字段的
view查看完整元数据,确认该包是否使用exports等替代字段。 - npm 与 pnpm 输出形态不同:核对主版本和
--json行为,不要依赖人类可读文本做固定解析。
兼容性提示:当前 pnpm 文档将 pnpm view 标记为自 v11.0.0 提供;旧版 pnpm 环境可直接使用 npm view 查询同一注册表。
pnpm why <package>; npm explain <package>; npm ls [<package>...]分析某个包由谁引入、安装了哪些版本以及为何未被去重。
定位依赖来源
当某个包突然出现、安装了多个版本或体积异常时,先用反向依赖树找出“谁需要它”,再用版本树确认实际安装位置和版本范围。排查应在包含目标 package.json 与锁文件的项目根目录执行。
命令定位
pnpm 项目优先使用 pnpm why <包名> 查看反向依赖树:目标包位于顶部,下面逐级显示依赖它的包,直到工作区根项目。pnpm list <包名> --depth Infinity 用于核对所有已安装版本。
npm 项目使用 npm explain <包名> 查看引入链,使用 npm ls <包名> --all 查看逻辑依赖树。npm ls 输出的是逻辑关系,不一定等同于磁盘上的物理目录层级。
高频用法
在 pnpm 项目中同时查看来源和版本:
# 将 lodash 替换为需要排查的包名
PKG=lodash
pnpm why "$PKG"
pnpm list "$PKG" --depth Infinity预期输出(包名、版本和路径以实际项目为准):
lodash 4.17.21
└─┬ @example/tool 2.0.0
└── app@1.0.0
app@1.0.0 <PATH>
└─┬ @example/tool 2.0.0
└── lodash 4.17.21读取方法:从 lodash 分支向下追到工作区项目,即可确定直接引入者;若同一包出现多个版本,分别记录每条路径上的父包及其版本范围。在 npm 项目中查看同一信息:
# 将 lodash 替换为需要排查的包名
PKG=lodash
npm explain "$PKG"
npm ls "$PKG" --all预期输出(版本和路径以实际项目为准):
lodash@4.17.21
node_modules/lodash
lodash@"^4.17.21" from the root project
app@1.0.0 <PATH>
└── lodash@4.17.21读取方法:from the root project 表示直接依赖;若显示 from <父包>@<版本>,继续沿缩进向下即可追到根项目。
工作区中只排查某个子项目时,pnpm 使用 pnpm --filter <工作区包名> why <包名>;需要扫描全部工作区时使用 pnpm -r why <包名>。npm workspaces 可使用 npm explain <包名> --workspace <工作区名>。
为何没有去重
常见原因不是安装器失效,而是约束无法合并:
- 两个父包要求的语义化版本范围没有交集,例如一个要求
1.x,另一个要求2.x。 - peerDependencies 上下文不同。pnpm 中即使包名和版本相同,不同 peer 组合也可能形成不同实例。
- npm 使用了
nested或shallow等安装策略,物理布局不会像默认 hoisted 策略那样充分提升依赖。 - 锁文件固定了旧的可兼容版本,安装器不会在普通冻结安装中主动重算整个依赖图。
- 工作区存在不同的 overrides、配置或本地链接依赖,导致解析结果不能共享。
先比较每条引入链声明的版本范围,再决定升级父包、统一 overrides 或执行去重。不要只看 node_modules 目录名判断是否重复。
风险与边界
npm dedupe 和 pnpm dedupe 会重新计算并修改依赖树,pnpm 还可能更新锁文件。触发条件是当前图中存在可被更高兼容版本替代的旧版本;后果可能是测试结果变化或锁文件产生大范围 diff。安全替代方案是先运行 npm dedupe --dry-run 或 pnpm dedupe --check,确认影响范围后再执行正式去重并跑完整测试。
不要通过手工删除 node_modules 中的某个嵌套包来“去重”。Node.js 解析可能因此找到错误版本或直接报模块缺失;应修改依赖约束或锁文件解析结果后重新安装。
排障清单
- 确认命令运行在正确的工作区根或子项目目录。
- 同时检查直接依赖、开发依赖、可选依赖和 peerDependencies。
- 对每个重复版本记录完整父链,不只记录最终包名。
- 检查
package.json中的 overrides、pnpm 配置和工作区过滤条件。 - 修改后使用冻结安装重新验证,确保锁文件与清单一致。
速查原则:why 或 explain 回答“谁引入”,list 或 ls 回答“装了什么”,版本范围与 peer 上下文回答“为何不能合并”。
锁文件与版本固定
pnpm install --lockfile-only; npm install --package-lock-only; pnpm install --frozen-lockfile; npm ci理解 package-lock.json 与 pnpm-lock.yaml 的作用、提交策略和更新时机。
管理锁文件
package-lock.json 与 pnpm-lock.yaml 用于固定实际解析出的依赖版本、来源、完整性校验及传递依赖关系。应用、服务和工作区应提交锁文件,并在 CI 使用冻结安装,避免同一提交在不同时间解析出不同依赖树。
文件职责
package.json 表达允许的版本范围和直接依赖意图;锁文件记录安装器最终选中的完整依赖图。修改依赖时应通过对应包管理器同步更新两者,不要把锁文件当作可独立维护的配置清单。
npm 的 package-lock.json 面向项目根目录,通常不会随 npm 包发布;node_modules/.package-lock.json 是 npm 的本地隐藏锁文件,不应提交。pnpm 工作区通常在根目录维护一个 pnpm-lock.yaml,由多个工作区包共享。
提交与安装策略
仓库只保留当前包管理器对应的锁文件。使用 pnpm 时提交 pnpm-lock.yaml,使用 npm 时提交 package-lock.json;不要同时维护两套会参与安装的锁文件。
在项目根目录执行以下脚本,可按现有锁文件选择冻结安装:
set -euo pipefail
if [ -f pnpm-lock.yaml ]; then
pnpm install --frozen-lockfile
elif [ -f package-lock.json ]; then
npm ci
else
echo "未找到 pnpm-lock.yaml 或 package-lock.json" >&2
exit 1
fi预期输出为以下一种,数量和耗时会不同:
Lockfile is up to date, resolution step is skipped
Already up to dateadded <COUNT> packages in <TIME>pnpm 在锁文件与清单不一致时会失败;npm ci 也会在 package.json 与 package-lock.json 不匹配时退出,而不是自动改写锁文件。这正是 CI 中需要的保护行为。
更新时机
以下情况应更新并提交锁文件:新增、删除或升级直接依赖;修改 overrides、peer 解析或工作区依赖;有计划地刷新传递依赖;切换了会改变依赖图的包管理器配置。
只更新锁文件而不写入 node_modules 时,可运行:
set -euo pipefail
if [ -f pnpm-lock.yaml ]; then
pnpm install --lockfile-only
git diff -- package.json pnpm-lock.yaml
elif [ -f package-lock.json ]; then
npm install --package-lock-only
git diff -- package.json package-lock.json
else
echo "未找到受支持的锁文件" >&2
exit 1
fi预期结果:
diff --git a/<LOCKFILE> b/<LOCKFILE>
<仅显示本次依赖解析产生的变更;无变化时 git diff 不输出内容>pnpm 的 --lockfile-only 不写入 node_modules,但相关命令仍可能同步 package.json;npm 的 --package-lock-only 主要更新锁文件解析结果。提交前必须阅读 diff,确认没有无关的大范围版本漂移。
冲突处理
锁文件冲突不要直接整文件选择“ours”或“theirs”,否则可能丢失另一分支的依赖变更。先解决 package.json 冲突,再用当前项目的包管理器重新生成锁文件,随后执行冻结安装和测试。推荐顺序:
- 合并并确认所有
package.json的依赖声明。 - 运行
pnpm install --lockfile-only或npm install --package-lock-only。 - 检查锁文件 diff,确认两边新增或升级的依赖都存在。
- 运行
pnpm install --frozen-lockfile或npm ci。 - 执行构建、测试和安全扫描后再提交。
风险与边界
删除锁文件后重新安装会重新解析全部传递依赖。触发条件通常是“为了解决冲突或安装错误直接删锁”;后果可能包括大量版本升级、行为变化和供应链风险。安全替代方案是从 Git 恢复锁文件,修正 package.json 或损坏条目后使用包管理器定向重算。
手工修改 resolved、integrity、版本键或 peer 快照可能导致完整性校验失败或安装出与声明不一致的树。应使用安装、更新、导入或锁文件修复命令生成这些字段。
不同 npm 或 pnpm 大版本可能升级锁文件格式并产生大 diff。团队应固定并统一包管理器版本,例如在 package.json 的 packageManager 字段中记录经过验证的精确版本,并在本地与 CI 使用同一主版本。
排障清单
- 确认当前命令与仓库锁文件属于同一种包管理器。
- 检查
package.json是否已修改但未同步锁文件。 - 查看 Git diff,区分预期依赖更新与无关格式重写。
- CI 失败时先在相同包管理器版本下执行冻结安装复现。
- 完整性错误不要直接覆盖校验值,先确认代理、私有仓库或上游制品是否发生变化。
速查原则:日常安装信任已提交锁文件;有意修改依赖时更新并审查锁文件;CI 始终采用不会自动改写锁文件的安装方式。