本地能跑 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 并存时,改错文件的情况非常常见。
查看「工程效能」全部文章 →

同分类文章

查看 0 评论 0

评论

正在加载评论…

留言提交后自动审核:正常内容立即显示,含敏感信息的会转人工复核。

本地能跑 CI 装不上:lockfile 漂移的三种典型成因 - 起航社区