Jenkins 构建 Node 项目报错解析与解决——pnpm lockfile 问题实战

在使用 Jenkins 自动化构建 Node.js 项目时，经常会遇到类似报错：

ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json
Error: Cannot find module 'node_modules/vite/bin/vite.js'

对于初学者来说，这种报错可能很迷惑。本文带你从原理到实操，彻底搞懂问题原因和解决方案。

---

一、问题现象

在 Jenkins CI 上执行构建任务时，可能出现以下情况：

1. pnpm install 失败，报错：

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

2. 构建命令报错：

   Error: Cannot find module 'node_modules/vite/bin/vite.js'

3. 打包步骤失败：

   zip warning: name not matched: dist
   zip error: Nothing to do!

---

二、问题根源分析

1. pnpm lockfile 不一致

• pnpm 使用 pnpm-lock.yaml 来锁定依赖版本，保证不同环境安装依赖一致。

• CI 环境（如 Jenkins）默认启用 frozen-lockfile 模式，即：

  • 不会自动修改 lockfile
  • 如果 package.json 中新增或修改了依赖，而 lockfile 未更新，就会报错。

典型场景：

• 本地新增依赖：

pnpm add @zxing/browser jsqr qrcode-decoder quagga

• package.json 改了，但 pnpm-lock.yaml 没更新或没提交到 Git。
• Jenkins 在 CI 环境拉取代码后，执行 pnpm install 时就报错了。

---

2. node_modules 缺失

由于 pnpm install 失败：

• node_modules 没生成完整依赖

• 构建工具（如 Vite）找不到模块：

  Cannot find module 'node_modules/vite/bin/vite.js'

• 构建中断 → 打包 dist 文件失败

---

三、解决方案

1. 本地更新 lockfile 并提交（推荐）

1. 在本地项目根目录执行：

pnpm install

• 会根据 package.json 更新 pnpm-lock.yaml。
• 注意不要使用 --frozen-lockfile，否则不会更新。

2. 提交更新：

git add package.json pnpm-lock.yaml
git commit -m "chore: update lockfile after adding new dependencies"
git push

3. Jenkins 再次构建：

• CI 拉取最新代码
• pnpm install 会顺利安装依赖
• 构建正常 → 打包成功

---

2. CI 临时解决方案（不推荐）

如果只是测试或临时构建，可以在 Jenkins 构建脚本里加：

pnpm install --no-frozen-lockfile

• 会忽略 lockfile 和 package.json 的不一致
• 强制安装依赖
• ⚠️ 风险：可能导致不同环境依赖版本不一致，不适合长期使用

---

3. 确保构建路径正确

在 Jenkins 中，确保工作目录存在：

cd /var/jenkins_home/workspace/jxc-web
pnpm install

• 如果 workspace 被清理或不存在，会报：

  Error: ENOENT: no such file or directory, uv_cwd

• Jenkins job 配置中可以取消"构建前删除工作区"，或者在构建脚本里自动创建目录：

mkdir -p /var/jenkins_home/workspace/jxc-web

---

4. 检查 Node.js 和 pnpm 版本

确保 Jenkins 使用的 Node.js 与本地一致：

node -v
pnpm -v

不同版本可能导致依赖安装或 vite 构建失败。

---

四、Jenkins 构建推荐流程

一个推荐的 Jenkins 构建脚本：

#!/bin/bash
set -e

# 确保工作区存在
mkdir -p /var/jenkins_home/workspace/jxc-web
cd /var/jenkins_home/workspace/jxc-web

# 拉取最新代码
git reset --hard
git clean -fd
git pull origin main

# 安装依赖
pnpm install --frozen-lockfile

# 构建项目
pnpm run build:dev

# 打包 dist
zip -r dist.zip dist

✅ 关键点：

• --frozen-lockfile 保证 CI 与 lockfile 一致
• 如果 lockfile 有变动 → 在本地更新并提交
• 确保 workspace 路径存在，避免 uv_cwd 错误
• Node.js、pnpm 版本与本地一致

---

五、总结

• Jenkins 不会自动更新 pnpm lockfile → 锁文件必须与 package.json 保持一致

• 构建失败 的根本原因是依赖没装完整

• 最佳实践：

  1. 本地修改依赖后同步更新 lockfile
  2. 提交到 Git
  3. CI 使用 --frozen-lockfile 保证环境一致

这样就可以避免：

• ERR_PNPM_OUTDATED_LOCKFILE
• Cannot find module 'vite'
• 打包 dist 失败

---

小白提示：

每次新增依赖后记得跑 pnpm install 并提交 pnpm-lock.yaml，CI 构建才不会报错！

---