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 重新生成或更新。

package.json、package-lock.json 与安装结果的数据关系

用 npm ci 重建相同依赖

下面以 macOS/Linux 的 Bash 为例,创建一个最小项目,安装固定版本的 lodash,删除 node_modules 后再用锁文件重建。npm ci 会要求 package.json 与锁文件保持一致,并且不会为了适配新的依赖声明去改写锁文件。

bash
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"

预期输出:

text
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 的主版本,减少无意义的锁文件整体改写。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用依赖锁定文件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通