package-lock 都提交了,依赖还在天上飞
那周三早上,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 提交了就高枕无忧"的人:
npm install会改写 package-lock.json,npm ci不会。 install 的语义是"按 package.json 范围装最新并更新锁",ci 的语义才是"严格按锁装"。CI 用 ci,本地装依赖也尽量用 ci,要升级再单独、显式地执行 install,别混着用。
^和~是版本飘移的源头。 直接依赖写^,意味着每次 install 都可能拉到新的 minor/patch;间接依赖更不受你控制,上游一个发布就能让你的树变样。对关键依赖,把范围改成精确版本,是唯一可靠的锁。
- review 代码时,一定要看 package-lock.json 的 diff。 很多人 review 只看业务代码,跳过 lock 文件那几千行变更——而依赖升级带来的 bug,恰恰藏在那些 diff 里。哪怕看不懂每一行,至少扫一眼有没有"非预期的版本号跳变"。
- "本地能跑"不代表"配置是对的"。 本地 node_modules 是历史装出来的缓存,能掩盖很多线上才会暴露的问题。定期删掉本地 node_modules 用
npm ci重装一次,能提前发现版本飘移。
最后
那次之后,我对"锁文件"的理解从"提交了就锁死"变成了"锁的是某一次的快照,而快照本身可能已经飘了"。
越是看起来"已经锁好了"的东西,越要问一句:锁的内容,是不是我真正想要的那个版本。
所以我写了。
希望你看完之后,下次 CI 挂了本地却能跑,第一反应是看 package-lock.json 里那个库到底锁的哪个版本、是怎么进去的,而不是像我一样,先怀疑 CI 缓存。
那个 ^,真的很重要。
- 点赞
- 收藏
- 关注作者
评论(0)