Node.js / 系统课时
使用依赖锁定文件
使用依赖锁定文件
同一份 package.json 如果只记录版本范围,不同时间重新解析依赖时可能得到不同的具体版本。依赖锁定文件把已经解析出的版本、来源与完整依赖树记录下来,再配合 npm ci,可以让开发机和 CI 按同一份依赖图安装。
学习目标
- 区分
package.json与package-lock.json分别负责什么 - 使用
npm ci按锁文件安装依赖,并验证实际安装版本 - 知道什么时候应更新并提交锁文件,而不是手工修改它
锁文件锁定的是解析结果
package.json 描述项目希望使用什么依赖。例如版本范围 ^4.17.0 允许 npm 在兼容范围内选择版本;package-lock.json 则记录某一次解析后实际选择的完整依赖图,包括精确版本以及用于校验包内容的信息。
| 文件 | 主要职责 | 应否提交到版本控制 |
|---|---|---|
package.json |
声明直接依赖、版本要求和项目配置 | 是 |
package-lock.json |
保存已经解析出的完整依赖树 | 应用项目通常应提交 |
node_modules |
保存本机实际安装的包 | 通常不提交 |
以现代 npm 为例,不要手工把 package-lock.json 中某个版本数字改掉。依赖树中还可能包含间接依赖、完整性校验和其他解析信息,应让 npm 根据 package.json 重新生成或更新。

用 npm ci 重建相同依赖
下面以 macOS/Linux 的 Bash 为例,创建一个最小项目,安装固定版本的 lodash,删除 node_modules 后再用锁文件重建。npm ci 会要求 package.json 与锁文件保持一致,并且不会为了适配新的依赖声明去改写锁文件。
rm -rf lock-demo
mkdir lock-demo
cd lock-demo
npm init -y >/dev/null
npm install lodash@4.17.21 --save-exact >/dev/null
rm -rf node_modules
npm ci >/dev/null
node -p "require('./package-lock.json').packages['node_modules/lodash'].version"预期输出:
4.17.21这个结果同时验证了两件事:锁文件中记录的是 4.17.21,删除现有安装目录后,npm ci 仍能按照锁文件恢复该版本。实际安装耗时、缓存位置和 npm 日志会因机器而异,因此示例把安装日志重定向掉,只检查确定性的版本结果。
更新依赖时一起更新锁文件
需要升级依赖时,应通过 npm 命令修改依赖并让它同步更新锁文件。例如把直接依赖明确更新到 4.17.21 时,可以执行 npm install lodash@4.17.21 --save-exact;随后检查 package.json 和 package-lock.json 的 diff,并把两者放在同一个提交中。
团队中可以采用一个简单规则:日常拉取代码和 CI 使用 npm ci,主动增加、删除或升级依赖时使用 npm install。如果只改了 package.json 却没有更新锁文件,CI 中的 npm ci 会因两者不一致而失败,这正是它帮助发现依赖漂移的方式。
遇到锁文件冲突时重新解析
多人同时升级依赖时,package-lock.json 很容易出现 Git 冲突。不要只为消除冲突标记而拼接两边的 JSON;先确认最终 package.json 应保留哪些依赖,再让 npm 根据最终声明重新解析,然后重新执行安装验证。
可检查三个结果:git diff 中直接依赖是否符合预期,npm ci 能否从空的 node_modules 成功安装,以及项目测试是否通过。不同 npm 主版本可能使用不同的 lockfileVersion,团队最好同时固定 Node.js 与 npm 的主版本,减少无意义的锁文件整体改写。