Jenkins Vue 流水线 pnpm install 报 ERR_PNPM_OUTDATED_LOCKFILE 排查

记录时间：2026-08-03
环境：Jenkins 共享库（ops-jenkinsfile）· Vue 前端流水线 vueDevopsByk8s.groovy · 业务项目 gzeport-gzsw-ui · pnpm 10.22.0 / node 20.19.5

一、问题现象

构建 dyck-vue-gzsw-ui 时，前端构建阶段 pnpm install 失败，报错：

ERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with <ROOT>/package.json

  Failure reason:
  specifiers in the lockfile don't match specifiers in package.json:
* 1 dependencies were added: echarts@^6.1.0

随后「构建并推送镜像」阶段因前置失败被跳过。日志另有一条 WARN：

WARN Unsupported engine: wanted: {"node":"^22.14.0 || >=22.12.0"} (current: {"node":"v20.19.5","pnpm":"10.22.0"})

二、排查过程

2.1 确认流水线安装命令

查看 vars/vueDevopsByk8s.groovy，pnpm 分支安装命令为：

pnpm install --registry ${params.registryUrl} --dangerously-allow-all-builds

没有显式传入 --frozen-lockfile 或 --no-frozen-lockfile。

2.2 对比业务项目 package.json 与 pnpm-lock.yaml

对比 gzeport-gzsw-ui 的两个文件：

package.json 的 dependencies 中存在 "echarts": "^6.1.0"
pnpm-lock.yaml 的 importers 段没有任何 echarts 条目

即锁文件未包含新增依赖。

2.3 确认 pnpm 的 CI 默认行为

pnpm 在 CI 环境（检测到 CI 相关环境变量）默认启用 frozen-lockfile，锁文件与 package.json 不一致时直接拒绝安装，错误信息中也注明了这一点。

三、根因分析

业务项目新增了 echarts@^6.1.0 依赖，但 pnpm-lock.yaml 未同步更新并提交。pnpm 10 在 CI 下默认 frozen-lockfile 校验锁文件与 package.json 的一致性，发现失步即中断。这是业务侧依赖锁定规范问题，不是流水线脚本逻辑问题。

另需澄清：日志里的 Unsupported engine WARN 与业务项目 package.json 的 engines 字段（^22.14.0 || >=22.12.0）逐字一致，是项目自身声明的 node 版本要求，并非 echarts 的 node 限制，且该 WARN 不阻断安装。

四、解决方案

方案 A：业务侧更新锁文件（根治，推荐）

在业务仓库根目录执行：

pnpm install

pnpm-lock.yaml 会按现有 package.json 的 specifier 自动补上 echarts 条目，然后提交 package.json + pnpm-lock.yaml 两个文件，重新触发构建。这是 pnpm 官方 CI 最佳实践，保证构建可复现、依赖版本锁定。

方案 B：流水线临时绕过（不推荐长期）

在 vars/vueDevopsByk8s.groovy 的 pnpm 安装命令追加：

pnpm install ... --no-frozen-lockfile

代价：CI 每次会重新解析依赖并尝试更新 lockfile（CI 不提交、更新无意义），丧失依赖锁定与可复现性，且掩盖业务侧锁文件失步问题。

五、验证

业务侧本地执行 pnpm install，确认 pnpm-lock.yaml 的 importers 段出现 echarts 条目
提交 package.json + pnpm-lock.yaml 后重新触发 Jenkins 构建
预期：pnpm install 阶段通过，进入「构建并推送镜像」阶段

六、注意事项

Unsupported engine WARN 不阻断：源于项目自身 engines 声明 node ≥ 22.12，CI node 容器是 v20.19.5（低于声明）。工具链 vite@7.3.6（engines ^20.19.0 || >=22.12.0）、@vitejs/plugin-vue@6.0.7、sass@1.101.0（>=20.19.0）均支持 node 20.19+，node 20 构建大概率可行；若业务团队按 node 22 开发，建议把该项目的 nodeVersion 参数切到 22 与 engines 对齐（未验证）。
--dangerously-allow-all-builds 不要改动：pnpm 10+ 默认拦截依赖构建脚本，该开关是官方 CI 放行方式，不要改为固化某个项目的包名白名单。
新增依赖必须提交 lockfile：这是 CI 规范红线，开发本地加依赖后需把 package.json 与 pnpm-lock.yaml 一并提交，避免 CI 在 frozen-lockfile 下直接失败。

七、参考资料

发送评论编辑评论