📚 课程目录第3章锁文件机制

3. 锁文件机制

聊到包管理，有个东西绕不开——锁文件（lockfile）。

我记得刚入行那会儿，团队里有个项目经常出现「我本地能跑，你那边怎么报错？」的灵异事件。后来排查了半天，发现是依赖版本没锁住。有人装了 lodash@4.17.20，有人装的是 4.17.21，一个 patch 版本差异，把整个构建流程搞崩了。从那以后，我对锁文件的态度就一个字：锁！

3.1 锁文件到底在锁什么？

说白了，锁文件就是一份「依赖版本的快照」。它记录了项目里每个依赖包的确切版本号，以及它们的子依赖、子依赖的子依赖……整棵依赖树的全量信息。

你想想看，package.json 里写的是 "lodash": "^4.17.0"，这个 ^ 表示允许安装 4.x.x 的最新版本。今天装是 4.17.20，明天可能就变成 4.17.22 了。如果没有锁文件，不同时间、不同机器上安装的结果可能完全不同。

  锁文件的核心作用：
  确定性安装——同一份代码，在任何机器上安装的依赖版本完全一致
加速安装——锁文件记录了依赖树结构，安装时无需重新解析依赖关系
安全审计——可以追溯某个版本具体引入了哪些子依赖
离线安装——有了锁文件，配合缓存可以实现完全离线安装

注意：锁文件必须提交到版本控制系统中！我见过有人把 package-lock.json 加到 .gitignore 里，结果团队里每个人装的依赖都不一样，调试起来简直噩梦。

3.2 锁文件的生成与更新策略

锁文件是怎么来的？其实很简单——你执行 npm install 的时候，npm 会自动生成或更新 package-lock.json。yarn 同理，执行 yarn install 会生成 yarn.lock。

但这里有个坑：什么时候该更新锁文件？

我个人习惯遵循这几个原则：

新增依赖时——用 npm install <package> 安装新包，锁文件会自动更新
升级依赖时——用 npm update <package> 或手动改 package.json 后重新 install
删除依赖时——用 npm uninstall <package>，锁文件会同步清理
不要手动编辑锁文件——这玩意儿是机器生成的，手动改很容易搞坏依赖树

我的小技巧：在 CI/CD 流程中，我会加一个检查步骤——对比当前分支的锁文件和 package.json 是否匹配。如果不匹配，直接让构建失败。这样可以避免有人改了 package.json 却忘了更新锁文件。

我曾经踩过一个坑：有次为了修复一个紧急 bug，我直接在 package.json 里改了某个依赖的版本号，然后忘了执行 npm install。结果锁文件里还是旧版本，部署到线上后，依赖根本没更新，bug 依然存在。嗯，从那以后我养成了改完 package.json 必须重新 install 的习惯。

3.3 常见锁文件格式对比

不同的包管理工具，锁文件的格式和设计思路也不一样。我挑三个最常用的来聊聊。

特性	package-lock.json	yarn.lock	Cargo.lock
所属生态	npm (Node.js)	Yarn (Node.js)	Cargo (Rust)
文件格式	JSON	自定义文本格式	TOML
可读性	中等（嵌套结构较深）	较好（扁平结构）	较好（TOML 清晰）
冲突处理	容易产生合并冲突	冲突较少（扁平结构）	冲突较少（按包名排序）
完整性校验	使用 integrity 字段 (SHA-512)	使用 resolved + integrity	使用 checksum 字段
是否必须提交	是（官方推荐）	是	是（二进制 crate 必须）

来，我展开说说每个格式的特点。

package-lock.json

这是 npm 自带的锁文件格式。它是一个嵌套的 JSON 结构，每个依赖下面会列出它的子依赖。这种结构有个问题——如果依赖树很深，JSON 的嵌套层级会非常恐怖，合并冲突时很难处理。

// package-lock.json 片段
{
  "name": "my-project",
  "lockfileVersion": 2,
  "packages": {
    "node_modules/lodash": {
      "version": "4.17.21",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
      "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=="
    }
  }
}

注意：npm v7 之后引入了 lockfileVersion: 2，改进了性能。如果你还在用 npm v6 及以下，建议升级。我遇到过因为 lockfileVersion 不兼容导致安装失败的情况。

yarn.lock

Yarn 的锁文件采用自定义的文本格式，把所有依赖扁平化排列。这种设计的好处是——合并冲突少，可读性高。你看一眼就知道某个包被锁在哪个版本。

# yarn.lock 片段
lodash@^4.17.0:
  version "4.17.21"
  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaec6c3537e98ac8c5a4e2b8e7"
  integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==

我个人更喜欢 yarn.lock 的格式。为什么？因为它的条目是按包名排序的，查找某个依赖的版本非常快。而且扁平结构在 git 合并时冲突概率低很多。

Cargo.lock

Rust 生态的 Cargo 使用 TOML 格式的锁文件。TOML 本身就是为配置文件设计的，可读性非常好。Cargo.lock 会记录每个 crate 的精确版本、源码地址和校验和。

# Cargo.lock 片段
[[package]]
name = "serde"
version = "1.0.152"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bb7faf39e37b4153c4db3f8b5c8c2e8e0b1e3e6b8f5e6b5c5c5c5c5c5c5c5c5c5c"

做 Rust SDK 开发时，Cargo.lock 是必须提交到仓库的——尤其是当你发布二进制 crate 时。库 crate 可以不提交，但我建议还是提交，这样能保证所有开发者用同一套依赖。

3.4 锁文件的最佳实践

说了这么多，总结几条我这些年积累的经验：

锁文件必须提交到 Git——这是底线，没得商量
不要手动修改锁文件——用包管理工具的命令来操作
定期审查锁文件的变化——每次 PR 里看看锁文件变了什么，有没有引入不安全的依赖
使用 npm ci 代替 npm install——npm ci 会严格按照锁文件安装，不会做任何解析，速度更快也更安全
锁文件冲突时，重新生成——删掉锁文件，重新 install，然后提交新的锁文件

  一句话总结：锁文件是包管理的「安全带」，系上它，你才能放心踩油门。

好了，锁文件这块就聊到这儿。记住一句话：锁文件不是摆设，它是你项目的依赖契约。下次遇到「我本地能跑」的问题，先看看锁文件是不是被忽略了。