package-lock 都提交了,依赖还在天上飞

举报
yd_222034595 发表于 2026/11/07 08:56:31 2026/11/07
【摘要】 锁文件提交了、CI 用 npm ci,依赖还是飘了,本地能跑线上必挂的又一次翻车。

那周三早上,CI 突然红了:构建时报 Cannot read property 'map' of undefined,错在一个第三方解析库里。

本地跑同样的命令,绿得发亮。

我第一反应是经典的"环境差异"——但这次不一样,我明明把 package-lock.json 提交了,CI 用的也是 npm ci(严格按锁文件装,一个版本都不带偏的)。本地和线上应该装出一模一样的 node_modules 才对。

一通乱查

我自信满满地开始排查。

  • 是不是 CI 缓存了旧的 node_modules?清了 CI 缓存,重装,还是挂。
  • 是不是 Node 版本不一致?本地 18,CI 也 18,对得上。
  • 是不是那个库自己发布了有 bug 的新版本?我本地能用,说明我本地这个库是好的版本,那 CI 装的难道是另一个版本?
  • 去 CI 里 cat node_modules/那个库/package.json 看版本——果然是 3.4.0。
  • 回本地看,我的是 3.3.1。
  • 怎么回事?package-lock.json 不是应该锁死吗?我把本地的 package-lock.json 翻出来,找到那个库——锁的还真就是 3.3.1。

锁的是 3.3.1,CI 装出来是 3.4.0。这中间到底发生了什么?

真相

盯着两个版本号看了十分钟,我突然想起一件事:那个库不是我直接装的,是某个直接依赖间接拉进来的。

熟悉 npm 的人这时候大概要笑出声了。

package-lock.json 锁的是"整棵依赖树"没错,但有个前提:它锁的是上次 npm install 时的那棵树。而我的直接依赖 A,在 package.json 里写的是 ^2.0.0(允许 2.x 任意版本)。

事情是这样的:周二下午,同事在本地跑了一次 npm install(注意,是 install 不是 ci)。npm 发现 A 有个新发布的 2.5.0,符合 ^2.0.0,于是把 A 升到了 2.5.0;而 A 2.5.0 又依赖那个解析库的 ^3.0.0,刚好那天这个库发布了 3.4.0(带 bug),npm 顺手把它也升了。这一连串升级,全被写进了 package-lock.json,然后同事把更新后的 lock 文件提交了。

CI 用 npm ci 严格按这份新的 lock 文件装,装出来的就是 3.4.0——有 bug 的那个。

而我本地的 node_modules 还是上周装的、没更新过的 3.3.1,所以一直能跑。

也就是说:锁文件是"锁"了,但它锁的是一次悄悄发生的升级结果。 npm install 会更新 lock,^ 范围让间接依赖飘到最新,bug 就这么坐上了锁文件的顺风车,名正言顺地进了 CI。

解决也简单:把那个解析库的版本在 lock 里钉回 3.3.1,package.json 里关键依赖尽量用精确版本(去掉 ^),团队约定统一用 npm ci 装依赖,要升级就单独、显式地执行 install,改完必须 review lock 的 diff。

几条血泪教训

折腾三天换来的几句话,送给每一个觉得"lock 提交了就高枕无忧"的人:

  1. npm install 会改写 package-lock.json,npm ci 不会。 install 的语义是"按 package.json 范围装最新并更新锁",ci 的语义才是"严格按锁装"。CI 用 ci,本地装依赖也尽量用 ci,要升级再单独、显式地执行 install,别混着用。
  1. ^ 和 ~ 是版本飘移的源头。 直接依赖写 ^,意味着每次 install 都可能拉到新的 minor/patch;间接依赖更不受你控制,上游一个发布就能让你的树变样。对关键依赖,把范围改成精确版本,是唯一可靠的锁。
  1. review 代码时,一定要看 package-lock.json 的 diff。 很多人 review 只看业务代码,跳过 lock 文件那几千行变更——而依赖升级带来的 bug,恰恰藏在那些 diff 里。哪怕看不懂每一行,至少扫一眼有没有"非预期的版本号跳变"。
  1. "本地能跑"不代表"配置是对的"。 本地 node_modules 是历史装出来的缓存,能掩盖很多线上才会暴露的问题。定期删掉本地 node_modules 用 npm ci 重装一次,能提前发现版本飘移。

最后

那次之后,我对"锁文件"的理解从"提交了就锁死"变成了"锁的是某一次的快照,而快照本身可能已经飘了"。

越是看起来"已经锁好了"的东西,越要问一句:锁的内容,是不是我真正想要的那个版本。

所以我写了。

希望你看完之后,下次 CI 挂了本地却能跑,第一反应是看 package-lock.json 里那个库到底锁的哪个版本、是怎么进去的,而不是像我一样,先怀疑 CI 缓存。

那个 ^,真的很重要。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。