本地能跑 CI 装不上:lockfile 漂移的三种典型成因
本地 npm install 一切正常,CI 上 npm ci 直接报 lock 与 package.json 不同步。这类问题九成是 lockfile 漂移。这篇拆解三种成因、给出提交前的门禁命令,以及平台相关可选依赖的处理方式。
本地 npm install 一路顺风,推到 CI 上 npm ci 直接失败:npm ci can only install packages when your package.json and package-lock.json are in sync。或者更难受的一种——CI 装成功了,但装出来的版本和本地不同,测试行为跟着变。这两种都是 lockfile 漂移,只是表现不同。
成因一:装了依赖,没提交 lock
最常见也最无聊。本地 npm install some-pkg 更新了 package.json 和 package-lock.json,提交时只 add 了前者:可能 package-lock.json 在 .gitignore 里(历史遗留写法),也可能用 --no-save 装过东西,导致 lock 从未被更新。
排查很直接,看 lock 是否落后于 manifest:
git log --oneline -5 -- package.json package-lock.json
两个文件的最后修改提交不是同一个,基本就能确定。
成因二:包管理器或版本不一致
package-lock.json 有 lockfileVersion 字段,不同 npm 大版本生成的格式不同。本地用较新的 npm 生成 lock,CI 镜像里是较旧的 npm,npm ci 会尝试升级或直接报错。更隐蔽的是跨包管理器:本地用 pnpm 生成 pnpm-lock.yaml,CI 脚本却跑 npm ci,那等于根本没有 lock 可用,每一次安装都可能拿到不同的传递依赖。
判断办法很轻:打一下 lock 的 lockfileVersion,再和 CI 镜像里的 npm 大版本比一比,对不上就不用往下查了。
成因三:registry 与平台差异
两件事都属于这一类。
私有源不同步。 lock 里的 resolved 字段会把包地址写死。本地走公网 registry,CI 走内网镜像,镜像里缺某个版本的 tarball,安装就失败;反过来 lock 里写死内网地址,外部协作者就装不上。
平台相关可选依赖。 esbuild、rollup、sharp 这类包会按平台拆成多个 optionalDependencies。lock 里记录的是安装时所在平台的条目,本地 macOS 生成的 lock 到 Linux CI 上就可能缺条目,表现为「模块找不到」。npm 在较新版本里对这块做过修正,但跨架构(x64 与 arm64)仍然容易出问题。
提交前加一道门禁
最有效的做法是把漂移挡在合并之前,而不是等 CI 报错。--package-lock-only 只更新 lock、不动 node_modules,适合做检查:
npm install --package-lock-only
if ! git diff --exit-code package-lock.json; then
echo 'lockfile 漂移,请提交更新后的 package-lock.json'
exit 1
fi
CI 里同理,作为独立的一步跑在安装之前。配合固定版本:
{
"packageManager": "pnpm@9.1.0",
"engines": {
"node": ">=20 <21"
}
}
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: git diff --exit-code package-lock.json
npm ci 本身就会校验 lock 与 manifest 是否一致,不一致直接失败、不做修补。这正是它比 npm install 更适合 CI 的原因:npm install 会「帮你修好」,把漂移悄悄带进构建产物。
平台相关依赖怎么处理
不要手工删 lock 里的平台条目,下一次安装又会回来。可选的三条路:先保证安装环境的 os/cpu 与构建环境一致(统一基础镜像);pnpm 可以用 supportedArchitectures 声明需要包含哪些平台;确实要跨平台时,在 CI 的对应平台上重新生成 lock 并提交,而不是让运行时临时下载。
适用边界与常见坑
- 用
npm ci --dry-run可以只校验一致性而不真正安装,适合放在流水线最前面快速失败。 - 删掉 lock 重新生成是代价最高的修复,会一次性把所有传递依赖升到最新,等于顺手做了一次无人审查的升级。
- 不要为了「让 CI 过」而把
npm install写进流水线,那是把不确定引入构建。 - 私有源与公网源混用时,
resolved字段会锁死具体地址,换环境就装不上,最好在 CI 里用--registry统一入口。 - monorepo 里每个 workspace 的 lock 归属要明确,多份 lock 并存时,改错文件的情况非常常见。
正在加载评论…