Skip to content
返回维护与 LTS

锁文件管理

提交、解冲突并保持锁文件健康，使安装可复现且快。

为什么

锁文件是实际安装什么的唯一事实源 — 没它，npm install 在每台机器和每次 CI 产生不同树，"我机器上能跑"变"生产失败"。提交锁文件使安装可复现、确定、快（无解析步骤）。锁文件还钉死传递依赖，使依赖不能在你下面推破坏性传递升级。代价是 JSON 文件的合并冲突，机械可解 — 而不提交的代价是不可复现构建，远更糟。每个现代包管理器（npm、pnpm、yarn、pip、cargo、go）都支持并推荐提交锁文件。

何时使用

始终提交锁文件。合并触及 package.json 或锁文件时解冲突。

如何做

1. 提交锁文件：把 package-lock.json（或 pnpm-lock.yaml / yarn.lock）加入 git，绝不 gitignore
2. 冲突时：接受任一侧的 package.json，然后跑 npm install --package-lock-only 重新生成
3. 验证重新生成的锁文件干净安装：rm -rf node_modules && npm ci（ci = 从锁文件干净安装）
4. CI 中用 npm ci（非 npm install）— 锁文件与 package.json 不同步则失败，捕获漂移
5. monorepo：用单个根锁文件（pnpm workspaces）而非每包锁文件
6. 定期刷新：npm install --package-lock-only && npm audit fix 把安全补丁拉入锁

示例

# .gitignore — 不要忽略锁文件
# （若 .gitignore 中有 package-lock.json 则删掉）
node_modules/
# package-lock.json  <- 提交，不忽略

# CI 用 ci（干净安装）— 锁文件漂移则失败
# .github/workflows/ci.yml
- run: npm ci
- run: npm run build

# 解锁文件合并冲突
git merge feature-branch
# package-lock.json 冲突
git checkout --theirs package.json   # 或 --ours，然后：
npm install --package-lock-only      # 从解后的 package.json 重新生成锁文件
rm -rf node_modules && npm ci         # 验证干净安装
git add package.json package-lock.json
git commit

# 把安全补丁刷新进锁文件
npm audit fix --package-lock-only
git add package-lock.json && git commit -m "chore: 安全锁文件刷新"

常见问题

  • ⚠gitignore 锁文件 — dev 和 CI 安装不同，传递依赖只在生产推破坏性变更。
  • ⚠CI 用 npm install 而非 npm ci — 它悄悄更新锁文件，掩盖漂移而非失败。
  • ⚠手动编辑锁文件强塞版本 — 下次安装重新生成，你的编辑悄悄消失。

最佳实践

  • ✓始终提交锁文件并在 CI 用 npm ci — 可复现安装是可复现构建的基础。
  • ✓锁文件冲突靠重新生成（npm install --package-lock-only）解，绝不手合 JSON。
  • ✓每周跑 npm audit fix --package-lock-only 把安全补丁拉入锁而不改 package.json。