锁文件的重要性：一次血泪教训

Created on 2022年2月10日

前言

作为前端开发，你可能在 Google 或百度上搜索过这样的问题：package-lock.json 和 yarn.lock 到底有什么作用？是否需要提交到 Git 仓库？本文将通过我亲身经历的一次线上事故，让你深刻理解锁文件的重要性。

血泪教训：一次生产事故

事故背景

公司需要开发一个桌面端应用，技术栈选择了 Vue + Electron。在 Google 的帮助下，我找到了 vue-cli-plugin-electron-builder 这个插件。开发过程很顺利，功能测试也都通过了，于是项目成功上线。

项目上线后，由于我有强迫症，就把本地的项目删除了（当时觉得反正代码都在 Git 仓库里）。

事故发生

几个月后，需要修复一个 bug。我从 Git 仓库重新 clone 了项目，执行了熟悉的操作：

git clone <repository-url>
cd project
npm install  # 或 yarn install
npm run dev

然而，意外发生了——项目启动失败！

报错信息

报错信息显示找不到 graceful-fs 这个文件操作的异步模块。我当时整个人都懵了，明明之前能正常运行的代码，现在却启动不了。

排查过程

经过一番艰难的排查，我终于定位到了问题所在——锁文件！

准确地说，是因为我没有提交锁文件到 Git 仓库。

问题根源

查看 package.json：

{
  "devDependencies": {
    "electron-builder": "^22.2.0"
  }
}

注意那个 ^ 符号。当我重新安装依赖时：

第一次安装（项目开发时）：安装的是 [email protected]
第二次安装（从仓库克隆后）：由于 ^ 的存在，npm 会安装 22.x.x 的最新版本，比如 22.14.0

而恰好，electron-builder 在 22.2.0 到最新版本之间有破坏性变更，导致项目无法启动。

解决方案

最终，我从同事的电脑中找到了之前的 package-lock.json 文件，将它添加到项目中，重新安装依赖后，项目恢复正常。

# 删除现有的依赖
rm -rf node_modules

# 使用锁文件安装精确版本
npm ci  # 或 npm install

什么是锁文件？

锁文件的类型

不同的包管理器使用不同的锁文件：

包管理器	锁文件名称
npm	`package-lock.json`
yarn	`yarn.lock`
pnpm	`pnpm-lock.yaml`

锁文件的作用

锁文件记录了项目依赖的精确版本，包括：

直接依赖的精确版本
间接依赖（依赖的依赖）的精确版本
依赖的完整依赖树结构
依赖包的 hash 值（用于校验完整性）

锁文件示例

package-lock.json 的部分内容：

{
  "name": "my-project",
  "version": "1.0.0",
  "lockfileVersion": 2,
  "requires": true,
  "packages": {
    "node_modules/electron-builder": {
      "version": "22.2.0",
      "resolved": "https://registry.npmjs.org/electron-builder/-/electron-builder-22.2.0.tgz",
      "integrity": "sha512-...",
      "dev": true,
      "dependencies": {
        "graceful-fs": "^4.2.4"
        // ... 其他依赖
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.6",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.6.tgz",
      "integrity": "sha512-..."
    }
  }
}

为什么需要锁文件？

1. 确保依赖版本一致

没有锁文件的情况：

// package.json
{
  "dependencies": {
    "axios": "^1.0.0"
  }
}

团队成员在不同时间安装依赖：

开发者 A（1 月）：安装到 [email protected]
开发者 B（3 月）：安装到 [email protected]
CI/CD（5 月）：安装到 [email protected]

有锁文件的情况：

所有人安装的都是 [email protected]（锁文件中记录的版本）

2. 避免依赖的依赖版本不一致

假设 [email protected] 依赖 follow-redirects@^1.14.0：

没有锁文件：

不同时间安装可能得到不同版本的 follow-redirects
可能导致 bug 难以复现

有锁文件：

follow-redirects 的版本也被锁定
所有环境完全一致

3. 提高安装速度

锁文件包含了依赖包的确切位置和 hash 值，npm/yarn 可以：

跳过版本解析过程
直接下载指定版本
通过 hash 验证缓存有效性

4. 增强安全性

锁文件记录了依赖包的 integrity hash 值：

{
  "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q=="
}

这可以：

防止依赖包被篡改
确保下载的包与发布时完全一致
及时发现供应链攻击

常见场景分析

场景 1：团队协作

# 开发者 A
git clone project
npm install          # 使用锁文件安装
# 开发功能...
git add .
git commit -m "feat: add new feature"
git push

# 开发者 B
git pull
npm install          # 安装与 A 相同的依赖版本
# 继续开发...

结论：锁文件确保团队所有成员使用相同的依赖版本。

场景 2：CI/CD 部署

# .github/workflows/deploy.yml
steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3
  - run: npm ci # 使用 ci 命令严格按照锁文件安装
  - run: npm run build
  - run: npm run deploy

结论：确保生产环境的依赖版本与开发环境完全一致。

场景 3：版本升级

# 升级某个依赖
npm update axios

# 或指定版本
npm install [email protected]

# 锁文件会自动更新
git add package.json package-lock.json
git commit -m "chore: upgrade axios to 1.5.0"

结论：依赖升级时，锁文件会自动更新并记录新版本。

最佳实践

1. 永远提交锁文件到 Git

# ✅ 正确做法
git add package-lock.json
git commit -m "chore: update dependencies"

# ❌ 错误做法
# 将锁文件添加到 .gitignore

2. 使用正确的安装命令

场景	npm	yarn	pnpm
本地开发	`npm install`	`yarn`	`pnpm install`
CI/CD	`npm ci`	`yarn install --frozen-lockfile`	`pnpm install --frozen-lockfile`

为什么 CI/CD 要用不同的命令？

npm ci：严格按照锁文件安装，如果 package.json 与锁文件不一致会报错
npm install：会尝试更新锁文件以匹配 package.json

3. 定期更新依赖

# 检查过期的依赖
npm outdated

# 更新依赖
npm update

# 或使用工具
npx npm-check-updates -u
npm install

4. 处理锁文件冲突

当多人修改依赖时，可能出现锁文件冲突：

# 方法 1：重新生成锁文件（推荐）
git checkout --theirs package-lock.json
npm install

# 方法 2：使用工具自动合并
npx npm-merge-driver install -g

5. 不同包管理器不要混用

# ❌ 错误做法
npm install
yarn add lodash
pnpm add axios

# ✅ 正确做法 - 项目中只使用一种包管理器
npm install
npm install lodash
npm install axios

6. 为不同环境创建不同的锁文件策略

开发环境：

{
  "scripts": {
    "install": "npm install"
  }
}

生产环境：

{
  "scripts": {
    "install:prod": "npm ci --production"
  }
}

锁文件原理深度解析

依赖解析过程

读取 package.json
查找锁文件
解析依赖树
下载依赖包
验证完整性
安装到 node_modules

锁文件的作用就是将这些范围版本固定为精确版本。

语义化版本

版本号格式：主版本号.次版本号.修订号

主版本号：有破坏性的 API 变更
次版本号：向下兼容的功能新增
修订号：向下兼容的 bug 修复

1.2.3
│ │ └── 修订号（Patch）- bug 修复
│ └──── 次版本号（Minor）- 新功能
└────── 主版本号（Major）- 破坏性变更

真实案例分析

案例 1：left-pad 事件

2016 年，一个只有 11 行代码的 npm 包 left-pad 被作者从 npm 仓库中删除，导致依赖它的成千上万个项目构建失败。

如果有锁文件：即使包被删除，只要缓存中还有，就能正常安装。

案例 2：event-stream 后门事件

2018 年，黑客在 event-stream 包中植入了恶意代码，窃取比特币钱包信息。

锁文件的 integrity 校验可以及时发现包被篡改。

案例 3：颜色库破坏事件

2022 年，colors 和 faker 的作者故意在新版本中加入无限循环，导致依赖这些包的项目崩溃。

有锁文件的项目不受影响，因为版本被锁定在旧版本。

不同包管理器的锁文件对比

npm (package-lock.json)

{
  "name": "project",
  "version": "1.0.0",
  "lockfileVersion": 2,
  "requires": true,
  "packages": {
    "": {
      "name": "project",
      "version": "1.0.0",
      "dependencies": {
        "lodash": "^4.17.21"
      }
    },
    "node_modules/lodash": {
      "version": "4.17.21",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
      "integrity": "sha512-..."
    }
  }
}

特点：

JSON 格式，可读性好
包含完整的依赖树
支持多种 lockfileVersion

yarn (yarn.lock)

lodash@^4.17.21: version "4.17.21"
  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz"
  integrity sha512-...

特点：

自定义格式，更紧凑
相同版本范围的依赖会合并
确定性安装算法

pnpm (pnpm-lock.yaml)

lockfileVersion: 5.4

dependencies:
  lodash: 4.17.21

packages:
  /lodash/4.17.21:
    resolution: { integrity: sha512-... }
    dev: false

特点：

YAML 格式
支持硬链接，节省磁盘空间
严格的依赖隔离

总结

通过我的血泪教训，希望你能记住：

✅ 必须做的事

永远提交锁文件到 Git 仓库
使用 npm ci 在 CI/CD 环境中安装依赖
团队统一使用同一个包管理器
定期更新依赖并测试
遇到锁文件冲突时重新生成而不是手动合并

❌ 不要做的事

不要将锁文件添加到 .gitignore
不要手动修改锁文件
不要混用不同的包管理器
不要忽略锁文件的冲突
不要在生产环境使用 npm install（应该用 npm ci）

核心要点

锁文件不是可选项，而是现代前端项目的必需品。它确保了依赖版本的一致性，是项目稳定运行的基石。

记住这个教训：删除锁文件就像删除保险箱的钥匙，虽然保险箱还在，但你再也打不开了。