npm 工程手册：从依赖恢复到团队供应链治理
一位开发者执行 npm install 后项目可以启动，另一位在干净机器上却得到不同的间接依赖；CI 使用 npm ci 又因为 lockfile 与 manifest 不一致直接失败。表面看是三个安装结果，实质上是团队没有分清三类事实：package.json 表达允许的依赖范围，package-lock.json 记录一次确定的依赖树，node_modules 只是这棵树在当前机器上的物化结果。
npm 的工程价值不在于“能下载包”，而在于把依赖意图、解析结果、脚本入口和注册表访问变成可版本化契约。接下来沿着这条契约从第一次安装走到 CI、排障和供应链治理。
先确定故障属于 npm 依赖链，而不是相邻系统
当问题发生在 CLI 来源、配置层级、依赖解析、package-lock.json、node_modules、workspaces、项目脚本、缓存或 registry 访问时，应沿 npm 依赖链取证。Node.js 语法和前端框架行为需要回到对应运行时或框架定位；包发布与制品仓库服务端由发布链路负责；Nx、Turborepo 等任务图和远端缓存也不是 npm workspaces 的职责。workspaces 管理多包依赖恢复和命令作用域，不提供大仓增量构建能力。
这个边界直接影响排查顺序：npm ci 在解析前失败，应先比较 manifest、lockfile 与 CLI 版本；依赖已经恢复但业务运行报错，再进入 Node.js 或框架调用链。不要用更换包管理器掩盖尚未定位的应用故障，也不要让应用开发者通过直连公网绕过制品仓库策略。
在可清理目录记录 npm 的真实来源
使用非生产开发机和可删除的练习目录，机器安装项目支持的 Node.js。npm 通常随 Node.js 一起安装，但两者发布节奏不同，不能根据 Node 主版本猜测 npm 版本。先记录命令、配置和缓存实际来自哪里：
node --version
npm --version
npm config get registry
npm config get userconfig
npm config get cache把输出与根 package.json 的 packageManager、engines 和 CI setup 步骤放在一起比较。动态版本不能靠文章中的数字决定：先执行 node --version 与 npm --version，再到 npm CLI 版本支持说明确认目标 npm 所需的 Node.js 范围。项目支持的 Node 范围与 npm CLI 自身的运行范围是两份约束，必须同时满足。
安装、升级与版本约束
npm 官方建议通过 Node 版本管理器安装 Node.js 与 npm；这样项目切换 Node 版本时，CLI 来源也可追踪。无法使用版本管理器时，可以使用 Node.js 官方安装包。不要为了修复全局权限问题反复用管理员权限执行全局安装，这会把用户目录、系统目录和 CI 行为混在一起。
安装后先验证命令解析路径：
Get-Command node,npm | Format-Table Name,Source
node --version
npm --versionPOSIX 环境使用：
command -v node
command -v npm
node --version
npm --version只有在当前 Node 版本满足目标 npm 的支持范围，并完成代表项目验证后，才考虑独立升级 npm：
npm install --global npm@<approved-version>
npm --version项目可以在 package.json 中留下版本意图：
{
"engines": {
"node": ">=22 <25"
},
"packageManager": "npm@11.18.0",
"devEngines": {
"runtime": {
"name": "node",
"version": ">=22.9.0",
"onFail": "error"
},
"packageManager": {
"name": "npm",
"version": "11.18.0",
"onFail": "error"
}
}
}这里的版本号只是示范“精确基线”的形态，不是长期推荐版本。engines 面向包的运行兼容提示，devEngines 面向参与源码工作的开发环境，两者对象结构和执行时机不同。packageManager 是可读的工具声明，但不能假设所有 npm 旧版本都会据此自动切换 CLI；团队仍需通过版本管理器、开发容器或 CI setup 步骤提供实际版本。
安装渠道和权限问题应先查 Node.js 与 npm 的安装入口，主版本升级则同时查目标 CLI 的 release/support 页面。升级 PR 要记录旧、新 node --version 与 npm --version，并在代表项目上执行 npm ci、测试和脚本审批检查；只看到命令可以启动，不能证明依赖契约仍兼容。
依赖与磁盘模型
npm 安装要经过四个可观察阶段：读取 manifest 和配置、向 registry 获取元数据、计算理想依赖树、把树物化为 node_modules 并运行获准的生命周期脚本。lockfile 存在且与 manifest 相容时，解析以锁定结果为主；不相容时，npm install 会重新求解并可能改写 lockfile，而 npm ci 会拒绝继续。
npm 默认会在满足语义版本和 peer dependency 约束的前提下提升、去重依赖，因此 node_modules 看起来通常较平坦。平坦不代表所有包都可以合法引用根目录可见的任意依赖：源码只能依赖自己声明的包。依赖未声明却“恰好能 require”是幽灵依赖，树一旦去重方式变化就会暴露。
需要解释某个包为何出现时，不要翻目录猜测：
npm ls --all
npm explain <package-name>
npm query "#<package-name>"npm explain 给出引入路径，npm ls 展示物化树。两者和 lockfile diff 一起，才是评审依赖变化的证据。
配置与 registry
npm 配置来自命令行、环境变量、项目 .npmrc、用户 .npmrc、全局配置和内置默认值。排障时要问“最终值来自哪里”，而不是只打开仓库里的一个文件：
npm config list
npm config list --long
npm config get registry
npm config get proxy
npm config get https-proxy
npm config get cafile适合提交到仓库的项目 .npmrc 只放不敏感、需要团队一致的行为，例如：
registry=https://registry.npmjs.org/
save-exact=true
strict-peer-deps=true
fund=false企业 scope 可以映射到私有源：
@example:registry=https://packages.example.invalid/npm/
always-auth=trueexample.invalid 是保留示例域名。真实 registry、代理地址、CA 路径和认证方式应由组织配置注入。尤其不要在仓库 .npmrc 写真实 token、用户名密码或个人主目录绝对路径。
第一次跑通：证明 lockfile 可以恢复项目
在空目录创建以下 package.json：
{
"name": "npm-verify-lab",
"version": "1.0.0",
"private": true,
"scripts": {
"verify": "node -e \"const v=require('lodash/package.json').version; console.log('lodash='+v)\"",
"test": "npm run verify"
},
"dependencies": {
"lodash": "4.17.21"
}
}先生成并检查 lockfile：
npm install
npm test
npm explain lodash预期 npm test 输出 lodash=4.17.21，目录中出现 package-lock.json 和 node_modules，npm explain lodash 显示它由根项目直接依赖。将 package.json 与 package-lock.json 一起纳入版本控制，但不提交 node_modules。
接着模拟干净恢复：
Remove-Item -LiteralPath .\node_modules -Recurse -Force
npm ci
npm testPOSIX 环境将清理命令替换为 rm -rf node_modules。预期 npm ci 不修改 manifest 和 lockfile，测试仍输出相同版本。最后把 package.json 中 lodash 改为 4.17.20 而不更新 lockfile，再执行 npm ci；预期命令失败。这次失败正是契约生效，而不是 CI 不稳定。
练习结束后删除整个实验目录。不要在真实仓库里用递归删除命令做“顺手清理”。
lockfile 与可复现性
package-lock.json 描述 npm 生成的精确依赖树，应该提交。它不仅记录版本，还记录下载位置、完整性和包布局信息。代码评审至少回答：新增了哪些直接和间接依赖，来源是否改变，完整性字段是否异常变化，是否引入 Git/URL/file 依赖，生命周期脚本面是否扩大。
“有 lockfile”不等于“任何命令都可复现”。影响树形的选项也属于构建契约。例如 lockfile 是用 --legacy-peer-deps 或 --install-links 生成的，npm ci 需要相同设置。正确做法是把必要选项写入项目 .npmrc 并评审原因，而不是在某个 CI job 临时补参数。
日常操作可以这样分工：
开发者明确新增、删除或升级依赖时使用 npm install、npm uninstall、npm update，并提交 manifest 与 lockfile 的同一变更。代码评审、CI 和“从零恢复”使用 npm ci，让漂移直接失败。只想检查 lockfile 变化时使用 npm install --package-lock-only，但仍需随后执行完整恢复和测试。
npm audit fix 会执行完整安装并可能改变依赖树，不能作为无审查的 CI 自动修复步骤。
workspaces：多包依赖恢复，不等于任务编排平台
npm workspaces 由根 package.json 声明：
{
"name": "workspace-lab",
"private": true,
"workspaces": ["packages/*"],
"scripts": {
"test": "npm run test --workspaces --if-present"
}
}假设 packages/api 和 packages/shared 各自有 package.json，在根目录执行 npm install 会把 workspace 链接到根依赖布局，并由根 lockfile 记录整棵树。常用作用域命令是：
npm install lodash --workspace packages/api
npm run test --workspace packages/api
npm run test --workspaces --if-present
npm exec --workspace packages/api -- node --version要显式理解根是否参与：当指定 workspace 时，include-workspace-root 默认不把根项目加入执行。命令顺序、失败传播和跨包并行也不能凭参数名字猜测。需要 affected、任务图、远端缓存和跨语言构建时，应转到 31 家族，而不是继续把根 scripts 堆成隐形平台。
项目接入与常用操作
一个可维护的 npm 项目至少保留以下权威入口：
package.json # 依赖意图、工具约束、公开任务入口
package-lock.json # 精确解析结果，必须评审和提交
.npmrc # 可提交的非敏感项目行为
.npmrc.example # 仅在确有必要时说明私有源变量，不放真值
docs/dependencies.md# 特殊源、脚本准入和升级决策常用取证命令按问题选择：
npm outdated
npm ls --depth=0
npm explain <package>
npm config list
npm cache verify
npm doctor
npm audit --audit-level=high不要把 npm audit 的数量直接当风险结论。它依赖 registry 提供的 advisory 数据，可能包含不可达代码、仅开发依赖或无自动修复项；也可能漏掉未披露问题。合并策略需要记录影响路径、运行环境、补丁可用性、例外 owner 和到期日。
生命周期脚本：安装依赖就是执行第三方代码
依赖的 preinstall、install、postinstall，以及某些非 registry 来源的 prepare，可能在安装阶段执行。它们常用于编译原生扩展或下载平台二进制，也可能读取环境变量、文件和网络。CI 中拥有源码读取权和私有源 token 的安装进程，本身就是高价值执行环境。
npm 11 提供 allowScripts、strict-allow-scripts 与 npm install-scripts approve/deny 等逐包准入能力，具体命令和配置以项目实际 npm --version 对应的 依赖安装脚本文档 为准。旧项目的 ignore-scripts=true 是全关开关，不等于逐包审批；升级 npm 主版本时，要把脚本策略、已批准包版本和回滚方式一起迁移。
旧版本可先用隔离安装识别脚本需求：
npm ci --ignore-scripts
npm test如果测试失败，不要立即全局放开；先定位确实需要构建的包和版本。npm 11 当前官方能力允许维护逐包策略：
npm install-scripts ls
npm install-scripts approve <reviewed-package>
npm install-scripts deny <blocked-package>
npm install-scripts prune --dry-run默认审批可固定到已审查版本。团队还可以启用 strict-allow-scripts=true，让未审脚本成为失败。dangerously-allow-all-scripts 只是迁移逃生口，不应进入共享基线。这组命令属于 npm 11 的能力，不能套用于 npm 10；升级前应在代表仓库确认策略文件、原生依赖和回滚路径。
代理、CA 与凭证
代理优先通过受控环境变量或用户级配置注入：
npm config set proxy http://proxy.example.invalid:8080 --location=user
npm config set https-proxy http://proxy.example.invalid:8080 --location=user
npm config set cafile /path/to/corporate-ca.pem --location=user企业 TLS 拦截场景的正确修复是安装和指定受信 CA，不能把 strict-ssl=false 当长期方案。它会把“证书链不受信”变成“任何中间人都可接受”，同时掩盖代理配置错误。
消费私有包时，把 registry 路由放在项目配置，把凭证放在用户密钥存储或 CI secret。npm 官方给出的 CI 形态是项目 .npmrc 使用变量占位：
//registry.npmjs.org/:_authToken=${NPM_TOKEN}变量值由 CI secret 注入，不能提交真值。只做依赖安装的 CI 使用最小范围、只读、短有效期 granular token；发布凭证和安装凭证分离。输出 npm config list、调试日志或缓存键前先检查是否会暴露 registry、用户名、token、代理密码和内网路径。
常见失败：从现象反推哪一层变了
npm ci 报 manifest 与 lockfile 不一致
本机 npm install 能继续，CI 的 npm ci 失败。
比较 git diff -- package.json package-lock.json，确认是否只改了其中一个。
manifest 的依赖范围与锁定树不再相容，或生成 lockfile 时用了 CI 未继承的树形参数。
用批准版本的 npm 和项目 .npmrc 执行 npm install，评审并同时提交两个文件。
删除 node_modules，执行 npm ci && npm test，确认工作区无新 diff。
ERESOLVE 或 peer dependency 冲突
安装报告无法满足 peer dependency。
读取冲突双方的要求，执行 npm explain <package>，不要先加 --legacy-peer-deps。
插件与宿主版本不兼容，或过去宽松安装把冲突隐藏了。
升级/降级到共同支持范围，必要时替换依赖；只有明确接受兼容风险时才把例外写进项目配置。
干净 npm ci、测试和运行时关键路径同时通过。
registry 返回 401/403 或把 token 发错主机
公共包可安装，私有 scope 失败，或代理日志显示凭证去了非预期 host。
检查 npm config get @example:registry、认证键的 host/path 作用域和 token 权限。
scope 路由缺失、registry URL 尾部路径不同、凭证过期或权限过大但无读取目标包权限。
绑定到准确 registry，轮换为只读 token，并撤销可能泄露的旧 token。
npm whoami --registry=<approved-registry> 或安装一个批准的私有包；日志不得出现真值。
SELF_SIGNED_CERT_IN_CHAIN、超时或代理认证失败
浏览器可访问 registry，npm 连接失败。
记录 registry、proxy、https-proxy、cafile 最终值，使用 npm ping --registry=<url> 分离网络与依赖问题。
企业代理未配置、CA 链缺失、NO_PROXY 错误或代理账号未 URL 编码。
由安全/网络 owner 下发 CA 和代理配置，保持 TLS 校验。
npm ping、npm view <approved-package> version 和干净安装依次成功。
缓存报完整性错误或磁盘持续膨胀
下载包完整性失败，或 cache 占用增大。
先执行 npm cache verify，再区分 registry 内容变化、代理缓存污染、磁盘损坏和普通历史缓存。
npm cache 设计为可校验和自修复；盲目清空会删除排障证据，并让所有内容重新下载。
优先修复源或代理；只有证据指向本地损坏时才执行受控清理。
重新 npm cache verify，在空目录执行 npm ci，核对 lockfile 无变化。
CI 等价入口
CI 不应发明第二套构建方式。最小契约是：提供批准的 Node/npm 版本，注入只读 registry 凭证，恢复可验证缓存，执行 npm ci，再调用与本机相同的 scripts。
steps:
- name: versions
run: |
node --version
npm --version
- name: restore
run: npm ci
- name: verify
run: npm test缓存键至少包含操作系统、CPU/ABI、Node/npm 基线和 package-lock.json 摘要。优先缓存 npm 下载 cache，而不是跨 job 复用未经验证的 node_modules。缓存命中只能改善速度，不能成为构建正确性的前提；清空缓存后仍必须能从批准源恢复。
团队需要指定包管理 owner，但 owner 不替代代码评审。最低治理基线包括：
仓库只允许一种权威包管理器和一种 lockfile，混入 yarn.lock、pnpm-lock.yaml 时阻断合并。Node 与 npm 版本来源可重建，升级 PR 单独记录支持范围、lockfile 变化和回滚版本。新增依赖必须说明用途、维护状态、许可证、来源、脚本行为和替代方案。
私有源只给 scope 路由，凭证由用户/CI 注入；安装 token 只读且可轮换。CI 强制 npm ci，构建后工作区不得出现未提交的 manifest/lockfile diff。漏洞例外有 owner、影响判断、补偿控制和到期日，不能永久忽略。
lockfile 相同，平台产物仍可能不同
lockfile 可以锁定包版本，却不能消除操作系统、CPU、libc、Node ABI 和本机编译工具链差异。含原生扩展或 optional dependency 的项目必须在支持矩阵上验证，不能把一台 x64 开发机的 node_modules 复制给 Linux/ARM CI。判断标准是各目标平台都从 lockfile 干净恢复并通过关键测试。
提升布局会掩盖未声明依赖
根 node_modules 中“看得见”不代表包有权使用。升级 npm、增加依赖或执行 dedupe 后，幽灵依赖可能突然消失。治理手段是 lint/测试与干净安装，而不是固定一个偶然的目录形状。
安装脚本审批需要跟版本走
允许 sharp 执行脚本，不等于允许其所有未来版本。npm 11 的版本固定审批正是为了缩小信任范围。每次版本变化都应重新查看包来源、脚本和产物；对未知脚本先隔离安装，再决定批准、替代或阻断。
registry 镜像是供应链决策，不只是提速
镜像可能缓存旧元数据、改写 tarball、缺失签名或把 scope 路由到错误上游。团队要记录上游关系、同步延迟、故障旁路和完整性异常处理。绕过企业源直连公网会改变审计边界，也不能作为默认修复。
自动修复可能扩大变更面
npm audit fix 会重新解析并安装依赖；带 --force 时可能接受破坏性升级。生产仓库应把修复生成成普通 PR，展示 lockfile diff、测试、影响路径和回滚提交，而不是在流水线里静默改树。
清理、回滚与退出
依赖升级失败时，首先回滚 manifest、lockfile 和项目 .npmrc 的同一提交，再执行干净恢复：
git diff -- package.json package-lock.json .npmrc
npm ci
npm test不要只把 node_modules 换回旧目录，它不是可审计真相源。全局 npm 升级回滚也应使用明确版本，并确认 Get-Command npm/command -v npm 没有解析到另一套 Node 安装。项目退出 npm 时需要在一次受控迁移中删除 npm lockfile、替换 CI 和文档入口、生成目标工具 lockfile并验证，不保留多 lockfile“兼容”。
已记录 Node、npm、registry、userconfig 和 cache 的实际来源。package.json 与 package-lock.json 同步提交，仓库没有第二种 lockfile。干净目录执行 npm ci 后测试通过且工作区无 diff。
影响依赖树的参数已进入项目配置，不依赖个人命令历史。workspace 根、成员范围和根是否参与执行都有明确规则。安装脚本已识别并按版本审批；未使用长期全放开配置。
registry 路由与 token 分离，仓库和日志没有真实凭证。企业代理使用受信 CA，未关闭 TLS 校验。缓存可删除重建，缓存键包含 lockfile 与运行环境基线。
依赖升级、漏洞例外和包管理器升级都有 owner、验证和回滚路径。
改动依赖链时去哪里确认行为
安装行为或参数变化：查目标版本的 npm install 与 npm ci；前者可能更新依赖树，后者用于按 lockfile 干净恢复。
lockfile 出现大面积 diff：对照 package-lock.json 数据模型，先确认 CLI 主版本与生成规则，再评审包变化。配置来源不明或 scope 路由错误：查 npm 配置层级；不要凭一次 npm config set 猜测最终生效文件。
多包命令选错成员：查 npm Workspaces 和 Scripts，区分依赖边界、命令作用域与 shell 行为。
CI 访问私有包失败：按 CI/CD 消费私有包核对 token 类型、注入位置和 registry host，避免把发布凭证用于只读安装。