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 上执行构建任务时，可能出现以下情况：

pnpm install 失败，报错：

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'
打包步骤失败：

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 未更新，就会报错。

典型场景：

本地新增依赖：

bash 复制代码

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 并提交（推荐）

bash 复制代码

pnpm install

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

提交更新：

bash 复制代码

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

Jenkins 再次构建：

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

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

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

bash 复制代码

pnpm install --no-frozen-lockfile

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

3. 确保构建路径正确

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

bash 复制代码

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

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

Error: ENOENT: no such file or directory, uv_cwd
Jenkins job 配置中可以取消"构建前删除工作区"，或者在构建脚本里自动创建目录：

bash 复制代码

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

4. 检查 Node.js 和 pnpm 版本

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

bash 复制代码

node -v
pnpm -v

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

四、Jenkins 构建推荐流程

一个推荐的 Jenkins 构建脚本：

bash 复制代码

#!/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 构建才不会报错！