前端工程化 / 知识点
pnpm / npm 包管理速查手册
锁文件与版本固定
corepack use pnpm@<exact-version>; npm pkg set packageManager=<manager>@<exact-version>通过 packageManager 字段统一团队和持续集成环境使用的工具版本。
固定包管理器版本
在仓库根目录用 packageManager 写明“工具名@精确版本”,再让 Corepack 或持续集成环境按该字段安装并校验。这样可以避免开发机与流水线因 pnpm/npm 版本不同而反复改写锁文件。
基本配置
pnpm 项目可在根 package.json 中固定版本:
{
"name": "acme-app",
"private": true,
"packageManager": "pnpm@11.10.0"
}npm 项目使用同一字段:
{
"name": "acme-app",
"private": true,
"packageManager": "npm@11.19.0"
}packageManager 应提交到版本库,并与对应锁文件一起评审。不要写 pnpm@^11 或 npm@latest;浮动范围会让不同时间执行安装时得到不同工具版本。
固定并验证 pnpm
在已有 package.json 的仓库根目录执行:
set -e
# 当前 Node.js 环境没有 Corepack 时再安装,避免重复修改全局环境。
command -v corepack >/dev/null 2>&1 || npm install --global corepack@latest >/dev/null 2>&1
corepack enable pnpm
corepack use pnpm@11.10.0 >/dev/null 2>&1
printf 'declared=%s\nactual=pnpm@%s\n' \
"$(node -p "require('./package.json').packageManager")" \
"$(pnpm --version)"预期输出:
declared=pnpm@11.10.0
actual=pnpm@11.10.0corepack use 会更新根 package.json 的 packageManager。以后在该项目中调用 pnpm 时,应继续保留版本检查,确保 PATH 没有绕过 Corepack shim。
在持续集成中固定 npm
对于 npm,最直接的流水线做法是显式安装声明版本并断言结果。也可以在明确使用 Corepack 接管 npm 时执行 corepack enable npm。
set -e
npm install --global npm@11.19.0 >/dev/null 2>&1
test "$(npm --version)" = "11.19.0"
printf 'npm@%s\n' "$(npm --version)"预期输出:
npm@11.19.0只写 packageManager 但不启用版本管理、安装指定 npm 或校验版本,并不会自动替换当前 PATH 中已经存在的工具。
风险与边界
- 仅修改字段但未执行版本管理:旧的全局 pnpm/npm 仍可能被调用,后果是锁文件格式变化或安装结果不一致。安全做法是启用 Corepack,或在 CI 镜像中安装精确版本并执行版本断言。
- 直接升级包管理器主版本:可能重写锁文件、改变依赖解析或脚本安全策略。应在独立分支升级,重新安装、测试并单独评审锁文件差异。
- 在受限主机全局安装:可能因无写权限失败。优先使用预装好版本的 CI 镜像,或让 Corepack 在用户可写缓存目录中准备版本。
排障清单
corepack: command not found:安装corepack@latest后重试;不要假设所有 Node.js 安装方式都会附带 Corepack。- 声明版本与实际版本不一致:执行
command -v pnpm或command -v npm检查 PATH 是否仍指向旧的全局二进制,再重新启用对应 shim。 - 出现“项目配置为另一种包管理器”的错误:不要混用 npm 与 pnpm,按
packageManager指定的工具重新执行安装。 - CI 首次运行无法下载工具:为构建环境开放包注册表访问,或在镜像构建阶段预热并缓存指定版本。
速查:packageManager 负责声明,Corepack 或 CI 安装步骤负责兑现;两者缺一,版本就不算真正固定。
工作区与本地包
npm init --workspace <path> [--yes]; pnpm install配置 npm 或 pnpm workspace,集中管理多个应用和内部包。
创建工作区
工作区用于在一个仓库中集中管理多个应用和内部包,由根目录统一安装依赖、生成锁文件并运行子项目脚本。pnpm 在根目录使用 pnpm-workspace.yaml,npm 则在根 package.json 的 workspaces 字段中声明成员。
pnpm:创建可验证的工作区
下面脚本在临时目录创建 apps/web 和 packages/ui,并让 Web 应用通过 workspace:* 只解析本地 UI 包:
set -euo pipefail
WORKSPACE_DIR="${TMPDIR:-/tmp}/anystack-workspace-demo-$$"
mkdir -p "$WORKSPACE_DIR/apps/web" "$WORKSPACE_DIR/packages/ui"
cd "$WORKSPACE_DIR"
cat > package.json <<'JSON'
{
"name": "acme-monorepo",
"private": true,
"packageManager": "pnpm@11.10.0"
}
JSON
cat > pnpm-workspace.yaml <<'YAML'
packages:
- "apps/*"
- "packages/*"
YAML
cat > packages/ui/package.json <<'JSON'
{
"name": "@acme/ui",
"version": "1.0.0",
"main": "index.js"
}
JSON
printf "module.exports = 'ui';\n" > packages/ui/index.js
cat > apps/web/package.json <<'JSON'
{
"name": "@acme/web",
"version": "1.0.0",
"private": true,
"dependencies": {
"@acme/ui": "workspace:*"
}
}
JSON
command -v corepack >/dev/null 2>&1 || npm install --global corepack@latest >/dev/null 2>&1
corepack pnpm@11.10.0 install --reporter=silent
corepack pnpm@11.10.0 --filter @acme/web exec node -p "require.resolve('@acme/ui')"预期输出:
<PATH>/packages/ui/index.js实际绝对路径会不同;结果指向仓库内的 packages/ui/index.js,说明内部包已按工作区依赖链接,而不是从注册表下载。workspace:* 还会阻止 pnpm 在本地包缺失时静默回退到注册表中的同名包。

npm:对应配置
npm 不使用 pnpm-workspace.yaml,在根 package.json 中声明目录模式:
{
"name": "acme-monorepo",
"private": true,
"packageManager": "npm@11.19.0",
"workspaces": [
"apps/*",
"packages/*"
]
}子包仍各自保留 package.json。在根目录执行 npm install 时,npm 会识别已声明且版本匹配的本地工作区并创建链接;工作区之间使用普通 semver 范围,不要把 pnpm 专用的 workspace:* 直接复制到 npm 配置中。
高频用法
| 目标 | pnpm | npm |
|---|---|---|
| 安装全部工作区 | pnpm install |
npm install |
| 给 Web 应用加依赖 | pnpm --filter @acme/web add react |
npm install react -w @acme/web |
| 运行单个工作区脚本 | pnpm --filter @acme/web run build |
npm run build -w @acme/web |
| 运行全部已有测试脚本 | pnpm -r --if-present run test |
npm run test --workspaces --if-present |
--filter 和 -w/--workspace 建议使用包名而不是相对路径;包名稳定,目录重构后命令通常无需修改。批量运行脚本时加 --if-present,可跳过没有定义该脚本的工作区。
风险与边界
- 根包未设置
private: true:误执行发布命令时可能尝试发布聚合根包。安全做法是始终将工作区根包设为私有。 - 混用 npm 与 pnpm:会同时产生
package-lock.json和pnpm-lock.yaml,并可能得到不同依赖树。应先确定唯一包管理器,再在分支中清理另一种锁文件并完整重装验证。 - 内部包名称或版本不匹配:pnpm 的
workspace:*会直接安装失败,npm 也可能转向注册表解析普通版本范围。应确保子包name唯一、版本满足依赖声明,并给私有包使用组织作用域名称。 - 工作区范围过宽:如直接写
**,可能把示例、构建产物或临时目录识别成包。优先使用apps/*、packages/*等明确模式。
排障清单
- pnpm 提示未找到工作区:确认
pnpm-workspace.yaml位于仓库根目录,且packages模式能匹配含package.json的目录。 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND:核对子包name、工作区匹配范围和workspace:后的版本要求。- npm 提示
No workspaces found:确认命令从根目录执行,并检查根package.json的workspaces字段。 - 单个包脚本不存在:先检查该子包的
scripts;批量运行时使用--if-present跳过未定义脚本。 - 本地包没有被链接:删除错误的外部同名依赖声明,确认内部包版本满足范围,然后从根目录重新安装。
速查:pnpm 用 pnpm-workspace.yaml 加 workspace:* 强约束本地包;npm 用根 workspaces 字段和普通版本范围管理本地链接。
pnpm --filter <selector> <command> [<args>...]; npm run <script> --workspace <name-or-path>针对指定工作区及其依赖或被依赖项目安装依赖和运行脚本。
筛选工作区执行
在 Monorepo 根目录用 pnpm --filter 限定安装、构建或测试范围。选择器既能只匹配一个包,也能沿工作区依赖图包含它的依赖或被依赖项目,适合局部验证和 CI 分片。
基本语法
pnpm --filter "<selector>" <command>常用关系选择器:
@acme/web:只选择该包。@acme/web...:选择该包及其全部直接、间接依赖。@acme/web^...:只选择它的依赖,不包含自身。...@acme/ui:选择该包及所有依赖它的项目。...^@acme/ui:只选择它的被依赖项目,不包含自身。./packages/**:按工作区目录匹配。包含*、!等字符时建议整体加引号。
高频用法
安装应用及其工作区依赖,常用于只恢复某个应用所需的依赖集合:
pnpm --filter "@acme/web..." install预期输出:
Scope: 3 of 6 workspace projects
Lockfile is up to date, resolution step is skipped
Done in <TIME>Scope 表示命中的工作区数量;项目总数和耗时会随仓库变化。共享锁文件开启时,即使是筛选安装,也可能更新根目录的 pnpm-lock.yaml。
按依赖顺序构建目标应用及其依赖,前提是命中的包都声明了 build 脚本:
pnpm --filter "@acme/web..." run build预期输出:
Scope: 3 of 6 workspace projects
packages/core build$ node build.js
packages/ui build$ node build.js
apps/web build$ node build.js
Done in <TIME>修改公共包后,运行该包以及所有上游消费者的测试:
pnpm --filter "...@acme/ui" run test预期输出:
Scope: 3 of 6 workspace projects
packages/ui test$ node test.js
apps/admin test$ node test.js
apps/web test$ node test.js
Done in <TIME>生产脚本名和日志取决于各包的 package.json。若只想确认选择结果,可在各包上下文输出包名:
pnpm --filter "@acme/web..." exec node -p "process.env.npm_package_name"预期输出:
@acme/core
@acme/ui
@acme/web风险与边界
关系选择器可能一次命中大量项目。触发条件是公共底层包被许多应用依赖;后果是测试时间、缓存占用和发布范围扩大。先用输出包名的 exec 命令确认集合,再执行构建或发布。
默认未匹配到包时,部分命令可能无实际工作却正常结束,容易让 CI 误判成功。自动化环境建议加入 --fail-if-no-match:
pnpm --filter "@acme/web..." --fail-if-no-match run build预期结果:存在匹配包时执行构建;名称拼错或工作区未加载时以非零状态退出,不会静默跳过。
工作区依赖形成环时,脚本不能保证严格拓扑顺序。若构建依赖前后顺序敏感,应先消除循环依赖,或把共享类型和常量拆到无反向依赖的独立包中。
排障清单
No projects matched the filters:检查包名是否与目标package.json的name完全一致,并确认命令从工作区根目录执行。- 不带作用域的短名称匹配失败:仓库中可能存在多个同名包,改用完整名称,如
@acme/ui。 - zsh 中排除选择器报错:将选择器整体加引号,例如
--filter "!@acme/legacy"。 - 构建顺序异常:检查工作区依赖环,并确认内部依赖声明在正确的
dependencies或devDependencies中。
兼容性
npm 可用 --workspace=<name> 或重复多个 --workspace 定向执行,但没有 pnpm 的 ... 依赖图选择语法。需要自动包含依赖或被依赖项目时,使用 pnpm,或由任务编排工具显式计算项目集合。
pnpm --filter <consumer> add <package>@workspace:<range>在 Monorepo 中声明内部包依赖并避免错误拉取远程同名包。
引用本地工作区包
在 pnpm Monorepo 中用 workspace: 协议声明内部依赖,可以强制依赖解析到当前仓库的工作区包。目标包不存在或版本不满足时安装会直接失败,不会悄悄下载远程同名包。
前置条件
仓库根目录需要存在 pnpm-workspace.yaml,并覆盖内部包所在目录:
packages:
- "apps/*"
- "packages/*"packages/ui/package.json 必须声明唯一包名和版本,例如 @acme/ui@1.4.0。引用方应使用这个 name,而不是文件夹名。
基本语法
在 apps/web/package.json 中声明本地依赖:
{
"name": "@acme/web",
"private": true,
"dependencies": {
"@acme/ui": "workspace:^"
}
}workspace:^ 表示安装时必须使用本地工作区包;发布或打包时会转换为与本地版本对应的普通 ^ 版本范围。执行安装:
pnpm install预期输出:
Scope: all 3 workspace projects
Lockfile is up to date, resolution step is skipped
Already up to date
Done in <TIME>验证引用方实际链接到本地包:
pnpm --filter "@acme/web" list "@acme/ui" --depth 0预期输出:
@acme/web@1.0.0 <PATH>/apps/web
dependencies:
@acme/ui link:../../packages/ui看到 link:../../packages/ui 表示依赖来自当前工作区,而不是远程 registry;实际路径和版本可能不同。
常用范围
| 写法 | 本地安装约束 | 打包或发布后的版本范围 |
|---|---|---|
workspace:* |
接受当前本地版本 | 精确版本,如 1.4.0 |
workspace:^ |
接受当前本地版本 | ^1.4.0 |
workspace:~ |
接受当前本地版本 | ~1.4.0 |
workspace:^1.4.0 |
本地版本必须满足 ^1.4.0 |
^1.4.0 |
通常库包使用 workspace:^,既保证开发阶段只连本地包,又允许发布后的消费者接收兼容的次版本和补丁版本。必须锁死发布依赖时才使用 workspace:*。
高频用法
让 pnpm 自动把内部包加入指定工作区,可避免手工编辑 JSON:
pnpm --filter "@acme/web" add "@acme/ui@workspace:^"预期输出:
dependencies:
+ @acme/ui 1.4.0 <- ../../packages/ui
Done in <TIME>如果需要使用不同的依赖键名,可以声明工作区别名:
{
"dependencies": {
"@acme/design-system": "workspace:@acme/ui@*"
}
}生效行为:代码通过 @acme/design-system 导入,实际链接到本地 @acme/ui;发布前应检查产物中的别名是否已转换为普通 npm 依赖规格。
风险与边界
本地包缺失、名称拼错或版本不满足显式范围时,pnpm install 会失败。可能后果是 CI 阻断,但这比误装远程同名包更安全。先核对目标包的 name、version 和 pnpm-workspace.yaml 路径,不要把范围改成普通 registry 版本来绕过错误。
内部包互相引用形成循环时,pnpm 会警告工作区循环,脚本执行顺序也可能不稳定。安全做法是拆出无反向依赖的基础包,或重新划分运行时依赖与开发依赖。
发布前不要假设仓库内的软链接会进入产物。应通过 pnpm 的 pack 或 publish 流程生成包,使 workspace: 自动转换为标准版本范围,并在发布检查中核对生成的 package.json。
兼容性
workspace: 是 pnpm 使用的依赖范围协议。npm workspaces 通常把本地包保存为标准语义化版本范围,例如 ^1.4.0,再根据工作区名称和版本自动链接。团队不要混用 pnpm 与 npm 锁文件;应固定包管理器并在 CI 中使用同一种安装命令。
依赖解析与修复
npm pkg set overrides.<package>=<version>; pnpm install; npm install使用 overrides 或 pnpm.overrides 强制替换依赖树中的指定版本。
覆盖间接依赖
当上游依赖尚未升级、同一子依赖出现多个版本,或安全修复必须立即落地时,用 overrides 强制改变依赖树的解析结果。先用 npm explain 或 pnpm why 找到引入链路,再限定父包范围,避免把整个依赖树无差别改写。
基本配置
npm 只读取项目根目录 package.json 中的 overrides。下面仅覆盖 is-odd 引入的 is-number,不会影响其他父包下的同名依赖。
{
"name": "override-demo",
"version": "1.0.0",
"private": true,
"dependencies": {
"is-odd": "3.0.1"
},
"overrides": {
"is-odd": {
"is-number": "7.0.0"
}
}
}pnpm 11/12 建议在工作区根目录 pnpm-workspace.yaml 配置同一规则。
overrides:
"is-odd>is-number": "7.0.0"配置生效后必须重新安装并更新锁文件;只改清单、不更新锁文件,CI 的冻结安装通常会失败。
验证覆盖结果
在包含上述配置的项目根目录执行对应命令。
# npm 项目
npm install
npm explain is-number
npm ls is-number
# pnpm 项目二选一执行
pnpm install
pnpm why is-number
pnpm list is-number --depth Infinity预期输出会包含目标版本和父依赖链,排版可能因版本不同略有差异。
is-odd@3.0.1
└── is-number@7.0.0 overridden读取方法:先确认实际版本是 7.0.0,再确认它位于预期的 is-odd 分支;若其他分支也被替换,说明规则范围写得过宽。
高频用法
全局统一某个子依赖版本时,npm 可写 "overrides": {"pkg": "1.2.3"};pnpm 可写 overrides: {"pkg": "1.2.3"}。这种写法影响所有匹配边,适合经过兼容性验证的安全修复。
只覆盖指定父包时,npm 使用嵌套对象,pnpm 使用 "parent>child" 选择器。优先采用这种最小范围规则,便于回滚和定位副作用。
替换为维护中的分叉包时,可使用 npm 别名协议,例如 "pkg": "npm:@org/pkg@1.2.3"。发布前要检查许可证、构建脚本和包导出是否与原包一致。
风险与边界
覆盖规则会绕过上游声明的版本范围。触发条件是强制版本不满足父包预期,可能导致安装成功但运行时报 API 缺失、类型不兼容或构建失败;安全替代方案是先升级父包,无法升级时再用最小范围覆盖并执行完整测试。
不要删除锁文件来“刷新”结果。这样可能同时升级大量无关依赖,造成难以审计的变更;应保留锁文件,执行正常安装并只审查与覆盖规则相关的差异。
覆盖只能作为根项目策略。工作区子包或已发布依赖中的同名字段可能不会参与最终解析;应把规则集中放在仓库根,并让 CI 使用同一包管理器版本。
排障清单
- 运行
npm explain <包名>或pnpm why <包名>,确认真实父依赖。 - 检查规则是否写在仓库根,以及包名、作用域和版本选择器是否准确。
- 重新安装后检查
package-lock.json或pnpm-lock.yaml是否发生预期变化。 - 执行单元测试、构建和关键运行路径;仅看到安装成功不能证明兼容。
- 上游发布兼容版本后删除覆盖规则,再安装并确认依赖树恢复正常。
旧 pnpm 项目可能把规则写在根 package.json 的 pnpm.overrides 中;新项目应按锁定的 pnpm 主版本使用其当前配置入口,避免同时维护两份规则。
pnpm peers check; pnpm why <package>; npm ls --all; npm explain <package>识别并解决 peerDependencies 缺失、冲突和版本范围不兼容问题。
处理 Peer 依赖
出现 ERESOLVE、ERR_PNPM_PEER_DEP_ISSUES、unmet peer 或 invalid peer 时,先找出“插件要求的宿主版本”和“项目实际安装版本”。正确修复通常是补装宿主依赖或让宿主与插件版本范围对齐,而不是忽略检查。
快速定位
npm 使用依赖树和解释命令查看冲突来源;pnpm 11 及以上可直接检查锁文件中的 Peer 问题。
# npm
npm ls --all
npm explain react-dom
# pnpm
pnpm peers check
pnpm why react
pnpm list react react-dom --depth Infinity无问题时,pnpm peers check 会正常退出;有问题时会列出缺失或不满足范围的包。npm ls 中的 UNMET DEPENDENCY、invalid 和退出码非零都需要处理。
冲突示例与正确修复
下面先制造一个可复现冲突:react-dom@18.2.0 需要 React 18,而项目同时指定 React 17。
mkdir peer-demo
cd peer-demo
npm init -y
npm install react@17.0.2 react-dom@18.2.0预期输出包含以下关键行,日志路径和附加说明可能不同。
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! peer react@"^18.2.0" from react-dom@18.2.0把宿主与插件调整到兼容版本后重新安装并验证。
npm install react@18.2.0 react-dom@18.2.0
npm ls react react-dom预期输出:
peer-demo@1.0.0
├─┬ react-dom@18.2.0
│ └── react@18.2.0 deduped
└── react@18.2.0读取方法:同一安装上下文中应只有兼容的 React 主版本,且 npm ls 不再显示 invalid 或 UNMET DEPENDENCY。
常见处理方式
缺失 Peer 依赖时,在实际使用插件的应用或工作区包中显式安装宿主包,例如 npm install react@18.2.0 或 pnpm add react@18.2.0。不要把运行时需要的宿主只装在无关子包中。
版本范围冲突时,优先升级或降级插件,使多个插件接受同一宿主版本;其次调整宿主版本。变更后同时检查锁文件、构建结果和关键功能。
维护公共库时,把宿主声明在 peerDependencies,并让范围覆盖所有已验证版本。确实可选的集成可在 peerDependenciesMeta 中标记 optional: true,不要要求消费者安装永远不会使用的宿主。
pnpm 可用 strictPeerDependencies: true 让缺失或无效 Peer 在 CI 中直接失败。peerDependencyRules.allowedVersions 和 ignoreMissing 只应在已验证兼容、且短期无法等待上游修复时使用。
风险与边界
npm install --legacy-peer-deps 会忽略 Peer 契约。触发条件是依赖树无法正常解析,可能后果是构建通过但运行时加载两个不兼容宿主、Hook 或插件 API 异常;安全替代方案是对齐宿主和插件版本,必要时锁定已验证组合。
npm install --force 也可能把冲突树强行装入。它适合一次性诊断,不应写入 CI 或团队安装脚本;若必须临时使用,应记录原因、补充回归测试并设置删除期限。
pnpm 的 peerDependencyRules.allowedVersions 只改变告警判定,不会证明代码真实兼容。启用前应查阅上游变更、运行完整测试,并把规则限定到明确包和版本。
兼容性
npm 7 及以上默认尝试自动安装 Peer 依赖,无法构造一致依赖树时会报 ERESOLVE;npm 3 至 6 通常只告警、不自动安装。pnpm 当前默认会自动安装缺失的非可选 Peer,但遇到相互冲突的范围时需要人工选择版本。
排障时先确认团队使用的 npm/pnpm 主版本,再复现安装;不同主版本的自动安装、严格模式和错误输出可能不同。
pnpm dedupe; pnpm prune [--prod]; npm dedupe; npm prune [--omit=dev]减少重复安装的包并删除不再被 package.json 引用的依赖。
去重与裁剪依赖
用于依赖升级、切换分支或删除包后整理安装树:dedupe 合并可由同一兼容版本满足的重复依赖,prune 删除 node_modules 中不再被清单引用的多余包。两者都不能替代 npm uninstall 或 pnpm remove;要删除直接依赖,先修改 package.json,再整理安装树。
命令定位
| 目标 | npm | pnpm |
|---|---|---|
| 预检查重复依赖 | npm find-dupes |
pnpm dedupe --check |
| 执行去重 | npm dedupe |
pnpm dedupe |
| 预览多余包 | npm prune --dry-run |
暂无等价预览参数 |
| 删除多余包 | npm prune |
pnpm prune |
| 只保留生产依赖 | npm prune --omit=dev |
pnpm prune --prod |
npm 推荐流程
先确认工作区干净,再预览、去重、裁剪并检查顶层依赖。npm find-dupes 等价于去重的试运行,不修改安装树。
set -e
git status --short
npm find-dupes
npm dedupe
npm prune --dry-run
npm prune
npm ls --depth=0 >/dev/null
printf 'dependency tree checked\n'预期输出
dependency tree checked命令执行期间还会打印去重、裁剪和审计摘要,包数量与耗时随项目变化。出现最终标记表示所有命令均成功;随后重点审查 package-lock.json 的版本收敛变化,并运行项目测试。
pnpm 推荐流程
pnpm dedupe --check 在无需修改时返回成功;存在可去重项时返回非零状态,适合放入 CI 检查。随后执行去重和裁剪。
if pnpm dedupe --check; then
echo "lockfile already deduplicated"
else
echo "dedupe changes available"
fi
pnpm dedupe
pnpm prune
pnpm list --depth 0 >/dev/null
printf 'dependency tree checked\n'预期输出
lockfile already deduplicated
dependency tree checked或存在可去重项时:
dedupe changes available
dependency tree checkedpnpm 还可能打印解析和链接进度行。出现最终标记表示去重、裁剪和依赖检查均成功;完成后检查 pnpm-lock.yaml 差异,并执行 pnpm test 或项目约定的验证命令。
常用参数
npm install --prefer-dedupe 会在后续安装时优先复用兼容版本;npm prune --omit=optional 可移除可选依赖。pnpm 使用 pnpm prune --no-optional 移除可选依赖,使用 pnpm prune --prod 移除开发依赖。
风险与边界
- 在未提交锁文件时执行去重,可能让锁文件出现大量版本变化并掩盖非预期升级。安全做法是先提交或暂存改动,再审查锁文件差异并运行完整测试。
- 在开发机执行生产裁剪会删除构建、测试和类型检查工具,后续脚本可能报“命令不存在”。生产裁剪应只在部署目录或镜像运行阶段执行,开发环境需要时重新完整安装。
- 依赖版本范围或 peer 约束不兼容时,重复版本无法合并;不要用强制覆盖代替兼容性验证。
pnpm prune当前不递归处理 monorepo。需要生产依赖时,应在独立部署目录执行pnpm install --prod --frozen-lockfile,不要假设根目录裁剪已覆盖所有工作区。
排障清单
去重后仍有多个版本时,用 npm explain <PACKAGE> 或 pnpm why <PACKAGE> 找出版本范围和 peer 约束;裁剪后仍显示 extraneous 时,确认命令运行在正确的工作区根目录,并检查 file:、link: 或 workspace 链接。若构建突然缺包,先确认是否误用了 --omit=dev、--prod 或设置了 NODE_ENV=production。
仓库与发布环境
npm login [--registry=<url>] [--scope=<scope>]; pnpm login [--registry=<url>]配置作用域仓库、认证令牌和发布权限,避免凭据泄漏。
登录私有仓库
用于把包作用域绑定到指定私有 registry,完成交互登录或 CI 令牌认证,并在发布前验证账号与目标仓库。核心原则是:仓库地址与凭据必须按 host 或路径精确绑定,令牌不得写入会提交的项目文件。
npm 交互式登录
下面把 @mycorp 映射到私有仓库,登录后使用 whoami 验证令牌实际对应的账号。
set -eu
REGISTRY='https://registry.example.com/'
SCOPE='@mycorp'
npm config set "${SCOPE}:registry" "$REGISTRY"
npm login --scope="$SCOPE" --registry="$REGISTRY"
npm whoami --registry="$REGISTRY"预期输出
<USERNAME>登录阶段可能打开浏览器、要求用户名密码或提示二次验证;最终 whoami 应输出私有仓库用户名。若只看到公共 npm 账号,说明 --registry 或作用域映射错误。
pnpm 交互式登录
pnpm 11 及以上可直接登录。令牌默认写入用户级 pnpm 认证文件,不应提交到仓库。
set -eu
REGISTRY='https://registry.example.com/'
SCOPE='@mycorp'
pnpm login --scope "$SCOPE" --registry "$REGISTRY"
pnpm whoami --registry "$REGISTRY"预期输出
<USERNAME>pnpm 登录可能显示二维码、浏览器认证地址或传统凭据提示;以 pnpm whoami 的输出作为最终验证。
CI 使用令牌
把 NPM_TOKEN 配置为 CI 的受保护密钥。下面创建权限为 600 的临时用户配置,任务结束自动删除;默认使用 npm,执行前设置 PM=pnpm 可改用 pnpm。
set -eu
: "${NPM_TOKEN:?NPM_TOKEN is required}"
PM="${PM:-npm}"
REGISTRY='https://registry.example.com/'
AUTH_FILE="$(mktemp)"
trap 'rm -f "$AUTH_FILE"' EXIT
chmod 600 "$AUTH_FILE"
cat > "$AUTH_FILE" <<'EOF'
@mycorp:registry=https://registry.example.com/
//registry.example.com/:_authToken=${NPM_TOKEN}
EOF
NPM_CONFIG_USERCONFIG="$AUTH_FILE" "$PM" whoami --registry="$REGISTRY"预期输出
<USERNAME>若 registry 使用子路径,认证键也要包含相同路径,例如 //registry.example.com/repository/npm/:_authToken=...,否则客户端可能不发送令牌。
固定发布目标与权限
可在待发布包的 package.json 中固定 registry 和访问级别,避免开发机默认配置把包发布到错误仓库。restricted 适用于作用域包;永不发布的应用应直接设置 "private": true。
{
"name": "@mycorp/example",
"version": "1.0.0",
"publishConfig": {
"registry": "https://registry.example.com/",
"access": "restricted"
}
}该配置会让发布命令优先使用指定仓库和受限访问级别。发布前检查打包内容和目标,不实际上传:
set -e
npm pack --dry-run >/dev/null
npm publish --dry-run --access=restricted --registry=https://registry.example.com/ >/dev/null
printf 'publish dry-run passed\n'预期输出
publish dry-run passedpnpm 项目可对应使用 pnpm publish --dry-run --access restricted。
风险与边界
- 把令牌直接写在命令参数、日志或项目
.npmrc中,会进入 shell 历史、CI 日志或 Git。安全替代是交互登录、用户级认证文件、临时NPM_CONFIG_USERCONFIG或 CI 密钥注入。 - 使用覆盖整个仓库的长期 publish token,泄漏后可发布恶意版本。安装任务使用只读令牌,发布任务使用限定 scope、包、有效期和环境的最小权限令牌;仓库支持时优先使用受信任发布或 OIDC。
- 作用域未绑定或
publishConfig.registry缺失时,包可能发往默认公共仓库。发布前必须执行npm config get @mycorp:registry和publish --dry-run。 - 遇到私有 CA 错误时,不要用
strict-ssl=false绕过校验;应配置可信cafile。执行 logout 前确认令牌是否被其他环境共用,因为部分仓库会直接撤销该令牌。
排障清单
E401 通常表示令牌无效、过期或认证路径不匹配;E403 表示已认证但缺少读取、发布或 2FA 权限;E404 可能是 scope 指向错误仓库,也可能是仓库用 404 隐藏无权限资源。依次检查作用域 registry、whoami、令牌权限和包名,不要反复重试或把令牌打印出来。
npm publish [<package-spec>] [--access=public|restricted] [--tag=<tag>] [--dry-run]; pnpm publish [--access=public|restricted] [--tag=<tag>] [--dry-run]检查发布内容并设置版本、访问级别、标签和目标 registry。
发布软件包
用于在发布前核对包内容,设置新版本、访问级别、分发标签和目标 registry,并在确认无误后执行真实发布。单个包用 npm publish 或 pnpm publish;两者都应先做 dry-run。
发布前检查
先确认账号、包名、版本、private 标记和最终打包文件。private: true 会阻止发布;tarball 中不应出现源码密钥、测试数据或本地配置。
set -euo pipefail
npm whoami --registry=https://registry.npmjs.org/
npm pkg get name version private
npm pack --dry-run预期输出
<USERNAME>
{
"name": "@scope/package-name",
"version": "1.2.3",
"private": false
}
npm notice 📦 @scope/package-name@1.2.3
npm notice Tarball Contents
npm notice <SIZE> dist/index.js
npm notice <SIZE> package.json重点读取 name、version 和文件清单;<USERNAME>、<SIZE> 会随账号和包内容变化。若清单异常,优先修正 package.json 的 files、.npmignore 或构建产物,再继续发布。
设置版本并预演
patch、minor、major 按语义化版本递增。--no-git-tag-version 只改版本文件,不自动创建 Git 提交和标签,适合先审查变更。
# npm 项目
npm version patch --no-git-tag-version
npm publish --dry-run \
--access public \
--tag next \
--registry=https://registry.npmjs.org/预期输出
v<VERSION>
npm notice Publishing to https://registry.npmjs.org/ with tag next and public access (dry-run)
+ @scope/package-name@<VERSION>--dry-run 不上传包;确认 registry、tag、access 和 tarball 均正确后,再去掉该参数。next、beta 等标签适合预发布,稳定版本通常使用默认的 latest。
pnpm 等价操作
pnpm 11 及以上原生实现发布命令,并会执行发布生命周期脚本。工作区发布可结合 --filter 或 -r,但首次操作建议先限定单包。
pnpm version patch --no-git-tag-version
pnpm publish --dry-run \
--access public \
--tag next \
--registry=https://registry.npmjs.org/
# dry-run 核对通过后执行真实发布
pnpm publish \
--access public \
--tag next \
--registry=https://registry.npmjs.org/预期输出
dry-run:显示待发布包、版本、文件和目标 registry,不上传。
真实发布成功:+ @scope/package-name@<VERSION>风险与边界
同一 registry 中已发布的“包名 + 版本”不能再次发布;触发后会返回版本已存在错误,安全做法是提升版本而不是使用 --force。未指定 --tag 时通常更新 latest,预发布版本误挂到 latest 会影响普通安装,应显式使用 next 或 beta。
--access restricted 只适用于 scoped 包;非 scoped 包只能公开。发布脚本会运行 prepublishOnly、prepack、prepare 等生命周期钩子,脚本包含上传、生成或删除操作时可能改变产物,应先在干净工作区执行 dry-run。不要把 token 写进仓库或命令行参数,优先使用登录凭据、受保护的用户配置或 CI 密钥。
排障清单
ENEEDAUTH或 401:执行npm whoami --registry=<REGISTRY>,确认登录账号和 token 绑定的是同一 registry。- 403:检查包所有权、组织权限、2FA/OTP、访问级别和目标 scope。
EPUBLISHCONFLICT:版本已存在,提升package.json版本后重新打包。- 发布了错误文件:立即检查
npm pack --dry-run,后续版本通过files或.npmignore修正;不要假设删除旧版本后可复用版本号。 - pnpm 11 原生发布缺少旧 npm 代理能力时,可先执行
pnpm pack,再对生成的.tgz使用npm publish。
npm config set <proxy|https-proxy|cafile|strict-ssl> <value>; pnpm config set <httpProxy|httpsProxy|cafile|strictSsl> <value>在企业网络中配置 HTTP 代理、HTTPS 代理、自定义 CA 和严格证书校验。
配置代理与证书
用于企业代理、TLS 检查网关或私有 registry 环境。目标是同时配置 HTTP/HTTPS 代理、可信 CA 和严格证书校验,并通过实际 registry 请求验证链路。
npm 持久配置
代理服务器即使承载 HTTPS 请求,也常通过 http:// 地址接收 CONNECT;应按企业网络提供的实际地址填写。CA 文件必须是 PEM 格式,并包含完整签发链。
npm config set proxy "http://proxy.example.com:<PORT>"
npm config set https-proxy "http://proxy.example.com:<PORT>"
npm config set cafile "<PATH>/corp-root-ca.pem"
npm config set strict-ssl true
npm config get proxy
npm config get https-proxy
npm config get cafile
npm config get strict-ssl
npm ping --registry=https://registry.npmjs.org/预期输出
http://proxy.example.com:<PORT>
http://proxy.example.com:<PORT>
<PATH>/corp-root-ca.pem
true
npm notice PING https://registry.npmjs.org/
npm notice PONG <TIME>ms<PORT>、<PATH> 和 <TIME> 按实际环境变化。能返回 PONG 说明代理连接、TLS 校验和 registry 请求均已完成。
pnpm 持久配置
pnpm 11/12 的网络配置使用 camelCase 键;pnpm config set 默认写入可信的全局配置。项目级网络设置应放在 pnpm-workspace.yaml,不要依赖项目 .npmrc 承载普通网络参数。
pnpm config set httpProxy "http://proxy.example.com:<PORT>"
pnpm config set httpsProxy "http://proxy.example.com:<PORT>"
pnpm config set cafile "<PATH>/corp-root-ca.pem"
pnpm config set strictSsl true
pnpm config get httpProxy
pnpm config get httpsProxy
pnpm config get cafile
pnpm config get strictSsl
pnpm view npm version --registry=https://registry.npmjs.org/预期输出
http://proxy.example.com:<PORT>
http://proxy.example.com:<PORT>
<PATH>/corp-root-ca.pem
true
<VERSION>最后一行能返回版本号,说明 pnpm 已通过代理完成 HTTPS 请求。若只需当前终端临时生效,可设置 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY,避免修改用户配置。
export HTTP_PROXY="http://proxy.example.com:<PORT>"
export HTTPS_PROXY="http://proxy.example.com:<PORT>"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"
npm ping --registry=https://registry.npmjs.org/预期输出
npm notice PING https://registry.npmjs.org/
npm notice PONG <TIME>ms风险与边界
将代理用户名和密码直接写入 URL 会进入配置文件、日志或 shell 历史;触发后可能泄露企业凭据。安全替代方案是使用系统凭据代理、短期环境变量或经过 URL 编码的专用低权限账号,并限制配置文件权限。
关闭 strict-ssl 会跳过 registry 证书校验,代理劫持、错误 DNS 或中间人攻击都可能变成不可见风险。它只能作为短时诊断手段,确认问题后应立即恢复 true,并安装正确的企业根 CA,而不是长期保留 false。
cafile 只解决 npm/pnpm 自身的 registry HTTPS 请求。依赖通过 Git、Node 脚本、curl 或系统包管理器下载时,这些工具可能使用各自的代理和 CA 配置,需要分别处理。
排障清单
SELF_SIGNED_CERT_IN_CHAIN、UNABLE_TO_VERIFY_LEAF_SIGNATURE:CA 文件缺失、格式错误或链不完整;用企业签发链替换,并保持严格校验开启。- HTTP 407:代理要求认证;确认账号、URL 编码、代理白名单和凭据是否过期。
ETIMEDOUT、ECONNRESET:检查代理地址、端口、防火墙和NO_PROXY,再分别测试直连与代理路径。- 配置正确但 Git 依赖失败:检查
git config --global --get http.proxy和 Git 的 CA 配置,不能只排查 npm/pnpm。 - 清理配置时使用
npm config delete proxy、npm config delete https-proxy;pnpm 使用pnpm config delete httpProxy、pnpm config delete httpsProxy,随后重新执行连通性验证。
存储与安装排错
npm cache verify; pnpm store status; pnpm store prune检查、清理或重建 npm 缓存和 pnpm 内容寻址存储。
修复 npm 缓存与 pnpm Store
当安装出现完整性校验错误、缓存目录异常或磁盘占用持续增长时,先检查位置和完整性,再做清理。不要一开始就删除整个缓存或 Store;npm 缓存通常可自校验,pnpm Store 又可能被多个项目共享。
命令定位
先确认当前实际使用的目录,避免清理错用户、错磁盘或错 pnpm 配置。
npm config get cache
pnpm store path预期输出
<PATH>/.npm
<PATH>/pnpm/store/v<NUMBER>两行分别是 npm 缓存目录和 pnpm 当前 Store。实际路径及 Store 版本号会因系统、用户和 pnpm 版本而不同。
检查完整性
npm 优先执行 cache verify;它会验证索引与内容,并回收无用缓存数据。pnpm 使用 store status 检查 Store 中的包文件是否被修改。
npm cache verify
pnpm store status预期输出
Cache verified and compressed (<PATH>/_cacache)
Content verified: <COUNT> (<SIZE>)
Index entries: <COUNT>
Finished in <TIME>
Packages in the store are untouchednpm 输出重点看 Content verified 和是否出现校验错误;pnpm 成功时退出码为 0,表示 Store 内容与解包时一致。
高频修复
仅为释放磁盘空间时,优先清理未被项目引用的 pnpm 包:
pnpm store prune预期输出
Removed all cached metadata files
Removed <COUNT> files
Removed <COUNT> packages被移除的包以后仍可重新下载,现有项目不会因此删除依赖,但切换旧分支后的下一次安装可能变慢。
npm 校验仍持续报错,或必须回收全部缓存空间时才强制清空:
npm cache clean --force
npm cache verify预期输出
npm warn using --force Recommended protections disabled.
Cache verified and compressed (<PATH>/_cacache)
Content verified: 0 (0 bytes)
Index entries: 0
Finished in <TIME>清理后重新安装会从仓库下载依赖;离线环境应先确认所需包可重新获取。
Store 文件被修改、node_modules 由不兼容的 pnpm 版本创建时,可在项目目录强制重建链接和依赖:
pnpm install --force预期输出
WARN using --force I sure hope you know what you are doing
Packages: +<COUNT>
Done in <TIME>不同版本的提示文字可能略有差异;最终应以命令退出码为 0、安装完成且应用验证通过为准。
风险与边界
npm cache clean --force 的触发条件应是校验持续失败或明确需要回收全部缓存。它会丢失离线可复用内容,安全替代方案是先运行 npm cache verify。
不要在 pnpm 正安装时手工删除 Store。并发写入期间删除目录可能造成安装失败或链接异常,安全替代方案是停止相关进程后执行 pnpm store status、pnpm store prune,再按需运行 pnpm install --force。
遇到 tarball 完整性不匹配时,不要把清缓存当作唯一结论。若重试后仍指向同一下载地址,应检查私有仓库、代理缓存和锁文件来源,确认包内容可信后再更新校验信息。
排障清单
- 确认命令由预期用户执行,缓存与 Store 路径位于可写磁盘。
- 检查剩余磁盘空间、inode、杀毒软件或文件同步工具是否锁定目录。
pnpm store status报修改时,先排除手工改包或安全软件篡改,再重装。- 清理后仍失败,转查网络、证书、Node.js 版本、锁文件和原生模块构建日志。
速查顺序:定位目录 → 完整性检查 → 定向清理 → 重装验证。
npm doctor; pnpm install --reporter=ndjson; npm install --loglevel=verbose定位网络、权限、磁盘、Node.js 版本、原生模块和依赖解析错误。
排查 npm/pnpm 安装失败
安装失败时先保留第一处错误和完整日志,再按网络、权限、磁盘、运行时、原生模块或依赖解析分类。最终目标是修复根因后用锁文件完成一次可重复安装,而不是依靠 --force 临时跳过检查。
快速采集环境
以下命令可直接确认 Node.js、包管理器和仓库配置,并测试 npm 仓库连通性。
node -v
npm -v
pnpm -v
npm config get registry
pnpm config get registry
npm ping预期输出
v<MAJOR>.<MINOR>.<PATCH>
<VERSION>
<VERSION>
https://registry.npmjs.org/
https://registry.npmjs.org/
npm notice PING https://registry.npmjs.org/
npm notice PONG <TIME>版本、耗时和仓库地址可能不同。npm ping 失败时先处理 DNS、代理、TLS 或仓库服务,不要继续反复删除依赖目录。
保存可检索日志
在 Bash、Git Bash 或 CI Shell 中执行对应命令。日志重定向后,终端只显示退出码,详细错误保存在当前目录。
if [ -f pnpm-lock.yaml ]; then
pnpm install --reporter=append-only > install-pnpm.log 2>&1
code=$?
printf 'manager=pnpm exit=%s log=install-pnpm.log\n' "$code"
else
npm install --loglevel verbose > install-npm.log 2>&1
code=$?
printf 'manager=npm exit=%s log=install-npm.log\n' "$code"
fi
exit "$code"预期输出
manager=<npm|pnpm> exit=<CODE> log=install-<npm|pnpm>.log<CODE> 为 0 表示安装成功,非 0 表示失败。查看日志时优先搜索第一处 ERR!、ERR_PNPM_、EACCES、ENOSPC、node-gyp 或 ERESOLVE,末尾错误常只是连带结果。
分流处理

| 错误特征 | 先验证 | 安全处理 |
|---|---|---|
ENOTFOUND、ETIMEDOUT、ECONNRESET、证书错误 |
仓库地址、DNS、代理、企业 CA | 修正 registry、代理或 cafile;不要关闭 TLS 校验 |
EACCES、EPERM |
当前用户权限、文件是否被 IDE/杀毒软件占用 | 使用 Node.js 版本管理器或修正目录所有权;不要长期用 sudo npm -g |
ENOSPC |
磁盘空间与 inode | 删除构建产物,验证后清理 npm 缓存或执行 pnpm store prune |
EBADENGINE、Unsupported engine |
package.json 的 engines、项目固定版本 |
切换到项目支持的 Node.js 版本,优先使用受支持的 LTS |
node-gyp、make、MSBuild、Python 错误 |
是否有预编译包,当前 OS/CPU/Node ABI 是否支持 | 使用受支持的 Node.js 版本,或安装对应编译工具链 |
ERESOLVE、ERR_PNPM_PEER_DEP_ISSUES |
冲突包的要求范围和依赖来源 | 调整为兼容版本并重新生成锁文件,不把忽略冲突选项当长期方案 |
ERR_PNPM_OUTDATED_LOCKFILE |
package.json 是否变更但锁文件未提交 |
本地运行 pnpm install,审核并提交 pnpm-lock.yaml |
ERR_PNPM_UNEXPECTED_STORE |
当前 Store 路径与现有 node_modules 记录是否一致 |
在项目目录重新运行 pnpm install,让 pnpm 按当前 Store 重建 |
隔离安装脚本问题
依赖解析成功但安装阶段报原生编译、下载二进制或生命周期脚本错误时,可临时禁用脚本做一次诊断。该命令不等于最终安装。
if [ -f pnpm-lock.yaml ]; then
pnpm install --frozen-lockfile --ignore-scripts
elif [ -f package-lock.json ]; then
npm ci --ignore-scripts
else
echo "No pnpm-lock.yaml or package-lock.json found" >&2
exit 2
fi预期输出
Packages: +<COUNT>
Done in <TIME>npm 的输出格式可能显示 added <COUNT> packages。若禁用脚本后成功,问题集中在 preinstall、install、postinstall 或原生模块步骤;修复后必须正常重装并执行测试,因为部分包缺少安装脚本产物会在运行时失败。
风险与边界
触发 peer 依赖冲突时,--legacy-peer-deps、--force 或忽略 peer 错误可能生成能安装但运行不兼容的依赖树。安全替代方案是用 npm explain <PACKAGE> 或 pnpm why <PACKAGE> 找到来源,再调整直接依赖版本。
触发证书错误时,关闭 strict-ssl 会让中间人攻击或错误代理内容不再被验证。安全替代方案是导入可信企业 CA,并通过 cafile 配置证书链。
不要把删除锁文件作为第一步。它会重新解析整棵依赖树并扩大变更面;应先修复 package.json 与锁文件不一致、合并冲突或仓库缓存问题,再审核锁文件差异。
排障清单
- 第一处错误是否已保存,日志是否包含完整命令和退出码。
- 仓库、代理、CA、认证令牌是否属于当前环境,私有包是否有读取权限。
- 磁盘、inode、临时目录和项目目录是否可写。
- Node.js、npm/pnpm 版本是否符合项目声明,CI 与本地是否一致。
- 原生模块是否支持当前 OS、CPU、libc 和 Node ABI,构建工具链是否完整。
- 锁文件是否与清单同步,peer 依赖是否真正兼容。
- 修复后使用
npm ci或pnpm install --frozen-lockfile重装,并运行构建与测试验证。
速查原则:先分类,再做最小修复;任何绕过校验的选项都只用于定位,不作为长期配置。
pnpm install --lockfile-only; npm install --package-lock-only; git diff -- <lockfile>安全解决合并冲突并验证重新生成的依赖树没有意外变化。
处理锁文件冲突
锁文件冲突应先合并 package.json、工作区清单等“意图文件”,再由对应包管理器重算锁文件。目标不是消除 Git 标记即可,而是让合并后的依赖声明、锁定版本和 CI 安装结果保持一致。
先定位冲突
先确认哪些文件仍处于未合并状态,不要直接删除锁文件或对整份文件执行“全部采用当前分支”。
git status --short
git diff --name-only --diff-filter=U预期输出
UU package.json
UU pnpm-lock.yamlnpm 项目通常会显示 package-lock.json。先逐项合并 dependencies、devDependencies、peerDependencies、overrides 或 pnpm 的 catalog 配置,确认双方新增和升级意图都被保留。
pnpm 安全处理
pnpm 能基于已合并的清单重新解析 pnpm-lock.yaml。--lockfile-only 只更新清单和锁文件,--ignore-scripts 避免在冲突处理阶段执行依赖脚本;最后用冻结锁文件安装验证不会再次改锁。
# package.json 与工作区清单必须先完成手工合并
pnpm install --lockfile-only --ignore-scripts
# 两条命令都无输出才表示没有残留冲突标记或空白错误
git grep -n -E '^(<<<<<<<|=======|>>>>>>>)' -- package.json pnpm-lock.yaml || true
git diff --check
# 锁文件若仍与清单不一致,此命令会失败
pnpm install --frozen-lockfile --ignore-scripts预期输出
Lockfile is up to date, resolution step is skipped
Done in <TIME> using pnpm v<PNPM_VERSION>若第一条命令重写范围明显大于本次依赖变更,先检查执行 pnpm 的版本、注册表配置和工作区清单,不要立即暂存。
npm 安全处理
带冲突标记的 package-lock.json 通常不可解析。先保留一份完整锁文件作为基线,再依据已经合并的 package.json 只重建锁文件;npm ci 用于严格验证两者是否同步。npm 在清单范围与锁文件不一致时会按 package.json 更新锁文件。
# 以当前 HEAD 的完整锁文件作为可解析基线;不要同时采用两个分支的文本块
git show HEAD:package-lock.json > package-lock.json
# 只更新锁文件,不执行 install/postinstall
npm install --package-lock-only --ignore-scripts
# 会清理并重建 node_modules;建议在干净工作区或临时容器执行
npm ci --ignore-scripts预期输出
added <COUNT> packages in <TIME>如果当前 HEAD 不包含应保留的解析结果,也可以改用经过确认的提交:git show <COMMIT>:package-lock.json > package-lock.json。<COMMIT> 必须是你明确审查过的分支或提交。
验证依赖树
提交前至少完成以下检查:
git diff -- package.json pnpm-lock.yaml package-lock.json:直接依赖变化应与合并意图一致,不能出现无关的大范围升级。- pnpm 执行
pnpm list --depth 0,npm 执行npm ls --depth=0:顶层依赖版本和缺失、无效标记应符合预期。 - 在与 CI 相同的 Node.js 和包管理器版本下执行冻结安装或
npm ci。 - 运行项目的构建、测试和关键启动检查;锁文件语法正确不等于运行时一定兼容。
风险与边界
直接删除锁文件再安装会重新解析大量间接依赖,可能引入未经评审的升级;安全替代是保留一侧完整锁文件并由合并后的清单增量重算。盲目使用 --ours 或 --theirs 会丢失另一分支的依赖意图,而且在 rebase 中语义容易误判;应先比较清单,再选择明确的提交作为基线。
--ignore-scripts 能降低冲突处理时的代码执行风险,但可能让原生扩展或二进制下载尚未构建。完成脚本审查后,应在隔离环境中执行正式安装和测试。--fix-lockfile 适合修复损坏条目,不应替代合并差异审查。
脚本与依赖审计
pnpm install --ignore-scripts; npm ci --ignore-scripts; pnpm approve-builds [<package>...]审查 install、postinstall 等脚本,并在不可信项目中限制自动执行。
控制生命周期脚本
在首次打开外部仓库、审查依赖升级或处理供应链告警时,先阻止 preinstall、install、postinstall、prepare 自动执行,再按包和版本逐项放行。安装脚本拥有当前进程的文件、网络和环境变量权限,应按代码执行处理。
先审查项目脚本
先读取根项目声明的高风险生命周期脚本。该命令只解析本地 package.json,不会执行脚本。
node -e "const s=require('./package.json').scripts||{}; for (const k of ['preinstall','install','postinstall','prepare']) if (s[k]) console.log(k + ': ' + s[k])"预期输出
postinstall: node scripts/setup.js无输出表示根项目没有声明这四类脚本,但依赖包仍可能包含安装脚本。继续检查脚本引用的文件、下载地址、子进程、写入路径,以及是否读取令牌、SSH 配置或云凭据。
不可信项目先禁用
pnpm 与 npm 都可在安装时禁用生命周期脚本。两个命令二选一,必须使用仓库已有锁文件对应的包管理器。pnpm 项目执行:
pnpm install --ignore-scripts预期输出
Packages: +<COUNT>
Done in <TIME> using pnpm v<PNPM_VERSION>npm 项目在 CI 或已有锁文件时执行:
npm ci --ignore-scripts预期输出
added <COUNT> packages in <TIME>实际统计值可能不同。核心验收点是安装日志中没有依赖的 preinstall、install、postinstall 或 prepare 执行记录。npm 的 ignore-scripts 会阻止脚本自动运行;显式执行 npm run <SCRIPT> 仍会运行目标脚本,但不会带出对应的 pre/post 脚本。
pnpm 按包放行
在支持 allowBuilds 的 pnpm 11 中,把允许和拒绝结果提交到 pnpm-workspace.yaml。未列出的依赖构建脚本默认视为未审查;pnpm approve-builds 可交互或按名称写入策略。
allowBuilds:
esbuild: true
core-js: false配置生效行为:esbuild 可以执行安装构建,core-js 被明确阻止,其他带构建脚本但未列出的包会触发审查错误。可用以下命令核对并重新安装:
pnpm ignored-builds
pnpm install --frozen-lockfile预期输出
core-js输出表示该包的构建脚本被阻止。新增依赖后应重新检查列表,不要使用 dangerouslyAllowAllBuilds 作为长期配置。
npm 按版本审批
在支持脚本审批的 npm 11 中,先以禁用脚本方式安装,再列出待审查包。批准操作默认将已安装版本写入 package.json 的 allowScripts,拒绝操作写入长期的名称级拒绝规则。
npm ci --ignore-scripts
npm approve-scripts --allow-scripts-pending
# 审查对应版本的包内容后再执行
npm approve-scripts esbuild
npm deny-scripts core-js
# 未覆盖的安装脚本直接让安装失败
npm ci --strict-allow-scripts预期输出
added <COUNT> packages in <TIME>审批前可用 npm view <PACKAGE>@<VERSION> scripts --json 快速查看注册表元数据,但最终应审查锁文件锁定版本对应的实际包内容和脚本目标,而不是只看包名。
风险与边界
禁用脚本可能导致原生模块未编译、平台二进制未下载或生成文件缺失,典型结果是安装成功但启动时报“模块不存在”或二进制不可用。安全替代是先在无凭据、低权限、可销毁的容器中审查并只批准必要包,再执行 pnpm rebuild <PACKAGE> 或 npm rebuild <PACKAGE>;这两个 rebuild 命令本身会执行脚本,不能对未审查包使用。
不要在携带生产令牌、SSH Agent、云凭据或可写宿主目录的环境中测试未知脚本。prepare 还可能在 Git、文件或链接依赖安装时触发额外构建,因此不能只搜索 postinstall。npm 旧版本若不支持审批命令,应继续使用 --ignore-scripts,并通过隔离环境人工放行;pnpm 10 的旧策略字段与 pnpm 11 的 allowBuilds 不同,升级时应同步迁移配置。
pnpm audit [--prod] [--json]; npm audit [--omit=dev] [--json] [fix]检查已知安全漏洞并评估自动修复、手动升级和兼容性风险。
审计依赖漏洞
用于在发布、升级或事故排查前检查已知依赖漏洞,并决定是直接升级、自动修复、覆盖间接依赖,还是暂时接受风险。审计结果只覆盖注册表已收录的公告,不等同于完整代码安全扫描。
命令定位
在包含 package.json 和锁文件的项目根目录执行。npm audit 读取 package-lock.json/npm-shrinkwrap.json,pnpm audit 读取 pnpm 的依赖图;先确认使用的包管理器,不要混用锁文件。
下面的脚本会按锁文件自动选择命令,并把高危及严重漏洞作为重点:
set -euo pipefail
if [ -f pnpm-lock.yaml ]; then
pnpm audit --audit-level high
elif [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
npm audit --audit-level=high
else
echo "ERROR: 未找到受支持的锁文件" >&2
exit 2
fi预期输出(无已知漏洞时,实际措辞随版本不同):
No known vulnerabilities found或:
found 0 vulnerabilities退出码为 0 表示没有达到失败条件;发现漏洞时通常返回非零。注意:npm 的 --audit-level 主要控制失败阈值,不一定隐藏低等级条目;pnpm 会按阈值筛选显示内容。
常用参数
--json:输出机器可读报告,适合归档和 CI 解析。--prod/-P:只审计生产依赖;不要因此忽略会参与构建或发布的开发依赖。--dev/-D:只审计开发依赖,适合定位工具链风险。- npm
audit fix:在允许的依赖范围内尝试修复;先用npm audit fix --dry-run预览。 - pnpm
audit --fix:通常通过pnpm-workspace.yaml的 overrides 强制安全版本;pnpm 11+ 可用--fix=update仅更新锁文件中的包版本。
修复顺序
先用 npm explain <包名> 或 pnpm why <包名> 找到引入链,再按以下顺序处理:升级直接依赖;升级上游父包;为间接依赖添加临时 override;最后才考虑忽略公告。每一步都要提交锁文件变更,并执行测试、构建和关键业务回归。
自动修复后重新运行审计。报告仍存在时,检查“可修复版本”是否跨主版本、漏洞代码路径是否实际可达,以及替换包是否会改变 Node.js、peer dependency 或打包器兼容性。
风险与边界
触发 npm audit fix --force 时,可能安装超出当前版本范围甚至主版本升级,后果是 API 破坏、构建失败或运行时行为变化。安全替代方案是在独立分支手动升级目标依赖,审查锁文件差异后再合并。
触发 pnpm audit --fix 时,自动写入的 override 可能让父包运行在未测试的间接依赖版本上。安全替代方案是先查上游兼容声明,限定最小修复版本,并为 override 添加原因和移除条件。
不要在 CI 后追加 || true,否则高危漏洞会被静默放行。确需暂时忽略时,只按 GHSA 编号豁免,记录负责人、到期时间和不可利用的证据;pnpm 11 起应使用 GHSA,而不是旧的 CVE 忽略配置。
排障清单
- 审计请求失败:检查 registry、代理、证书和鉴权;网络失败不能解释为“无漏洞”。
- 报告只在某台机器出现:确认 Node.js、npm/pnpm 版本、锁文件和 registry 完全一致。
- 自动修复反复改锁文件:先恢复干净工作区,固定包管理器版本,再重新执行。
- 修复后仍报警:确认依赖链中是否同时存在多个旧版本,并检查 workspace 子项目是否全部更新。
速查结论:先审计、再定位依赖链、最后最小化升级;任何跨主版本或 override 修复都必须经过测试验证。
重装与回滚
pnpm install --frozen-lockfile; npm ci在依赖损坏或升级失败时备份锁文件、执行干净安装并恢复可用版本。
安全重装与回滚
用于处理 node_modules 损坏、安装中断、锁文件升级失败或分支切换后依赖异常。目标是保留当前清单和锁文件证据,用冻结安装重建依赖,并能恢复到已知可用版本。
安全重装
以下 Bash 脚本适用于 macOS/Linux。它先备份 package.json 和锁文件,再执行不会主动改写锁文件的干净安装;根目录和用户主目录会被拒绝,避免误删。
set -euo pipefail
test -f package.json || {
echo "ERROR: 当前目录没有 package.json" >&2
exit 2
}
case "$PWD" in
/|"$HOME")
echo "ERROR: 拒绝在危险目录执行" >&2
exit 3
;;
esac
stamp=$(date +%Y%m%d-%H%M%S)
backup="${TMPDIR:-/tmp}/dep-backup-$(basename "$PWD")-$stamp"
mkdir -p "$backup"
cp package.json "$backup/"
if [ -f pnpm-lock.yaml ]; then
cp pnpm-lock.yaml "$backup/"
rm -rf node_modules
pnpm install --frozen-lockfile
elif [ -f package-lock.json ]; then
cp package-lock.json "$backup/"
npm ci
elif [ -f npm-shrinkwrap.json ]; then
cp npm-shrinkwrap.json "$backup/"
npm ci
else
echo "ERROR: 未找到锁文件,停止重装" >&2
exit 4
fi
printf 'backup=%s\n' "$backup"预期输出(按包管理器出现其一,数量和耗时会变化):
Lockfile is up to date, resolution step is skipped
Packages: +<COUNT>
backup=<PATH>或:
added <COUNT> packages in <TIME>
backup=<PATH>npm ci 会校验清单与锁文件并重建整个依赖树;pnpm 的 --frozen-lockfile 会在锁文件缺失或与清单不同步时直接失败,而不是偷偷更新版本。
验证顺序
安装成功不代表应用可用。依次检查包管理器版本、运行仓库已有的测试和构建脚本,再启动最小业务路径。原生模块项目还要验证 Node.js ABI、操作系统架构和安装脚本是否正常执行。
若只在 CI 失败,对比 Node.js 版本、包管理器版本、环境变量、registry、代理和 .npmrc/.pnpmfile.cjs。若本地成功但容器失败,优先检查锁文件是否被复制、工作目录是否正确,以及缓存是否跨平台复用。
回滚到已知版本
优先从 Git 同时恢复 package.json 与对应锁文件,不能只回滚其中一个。下面以 <COMMIT> 为最后可用提交;根据项目保留匹配的锁文件参数。
COMMIT="<COMMIT>"
git restore --source="$COMMIT" -- package.json pnpm-lock.yaml
rm -rf node_modules
pnpm install --frozen-lockfile预期结果:
Lockfile is up to date, resolution step is skipped
Packages: +<COUNT>npm 项目将上面的锁文件替换为 package-lock.json,并把最后两行改为 npm ci;命令成功后,依赖树应与 <COMMIT> 中的锁文件一致。若没有 Git 提交,则从前一步输出的 <PATH> 恢复成对文件,再执行冻结安装。
风险与边界
直接删除锁文件再安装会重新解析整个依赖树,触发条件通常是“安装失败后想快速重建”。后果可能是大量间接依赖漂移、漏洞回归和不可复现构建。安全替代方案是保留锁文件,用 npm ci 或 pnpm install --frozen-lockfile 暴露真正的不一致。
在错误目录执行 rm -rf node_modules 会删除非目标项目依赖并造成长时间重装。安全替代方案是先验证 package.json、打印 pwd,并拒绝 /、主目录等危险路径。
使用 pnpm install --force 会重建不兼容的 modules 目录并重新获取被修改的 store 内容;它不是锁文件校验失败或完整性错误的通用修复。遇到 ERR_PNPM_TARBALL_INTEGRITY 时,不要盲目更新 checksum,先核验 registry、代理和 tarball 来源。
使用 --ignore-scripts 可用于判断是否由生命周期脚本导致失败,但原生模块、代码生成和二进制下载可能因此缺失。安全做法是仅用于诊断,确认脚本可信后恢复正常安装。
兼容性
Bash 脚本可在 macOS/Linux 直接运行;Windows PowerShell 删除目录使用 Remove-Item node_modules -Recurse -Force。npm ci 需要已有 package-lock.json 或 npm-shrinkwrap.json;pnpm 在 CI 且存在锁文件时通常默认启用冻结锁文件,但生产脚本仍建议显式写出 --frozen-lockfile。
速查结论:先备份清单与锁文件,再冻结重装;失败时修复版本或环境差异,不要通过删锁文件掩盖问题。