Jenkins执行脚本提示找不到pnpm命令

Question

在使用Jenkins执行前端构建脚本时，经常遇到“找不到 pnpm 命令”的错误提示。该问题通常出现在 Jenkins 构建节点未正确安装或配置 pnpm 时。虽然项目本地可能已通过 `npm install pnpm -g` 安装了 pnpm，但Jenkins执行构建任务时使用的 shell 环境可能与用户手动操作环境不同，导致无法识别全局安装的 pnpm。此外，若采用 nvm 管理 Node.js 版本，而未在 Jenkins 中正确加载 nvm 和 Node 路径，也会引发此问题。解决方法包括：确保 pnpm 在 Jenkins 执行环境中全局安装；在 Jenkinsfile 或构建脚本中显式设置 PATH 路径；或使用 `npm exec pnpm` 替代直接调用 pnpm。

Answer 1

1. 问题现象与初步排查

在 Jenkins 执行前端构建任务时，经常遇到如下错误：

Error: Command failed: pnpm build
sh: pnpm: command not found

尽管在本地开发环境中可以正常执行 pnpm build，但在 Jenkins 构建节点上却提示找不到命令。这通常表明 Jenkins 的执行环境与开发者本地使用的 shell 环境不一致。

• Jenkins 可能使用了不同的用户（如 jenkins 用户）来运行任务。
• 全局安装的 pnpm 没有被 Jenkins 的 PATH 包含。
• 若使用 nvm 管理 Node.js 版本，则可能未正确加载 nvm 环境变量。

2. Jenkins Shell 环境差异分析

Jenkins 执行脚本时使用的 shell 环境不同于用户手动登录系统时的 shell。例如：

环境类型	Shell 类型	PATH 差异	是否加载 .bashrc/.zshrc
本地终端	交互式 shell	包含用户自定义路径	是
Jenkins 构建节点	非交互式 shell	默认系统路径	否

因此，即使你在本地通过 npm install -g pnpm 安装了 pnpm，它可能只对当前用户的环境生效，而 Jenkins 使用的 shell 并未识别该路径。

3. Node.js 版本管理工具的影响（如 nvm）

如果项目使用 nvm 来管理多个 Node.js 版本，那么必须确保 Jenkins 在执行构建前已正确加载 nvm 和对应的 Node.js 路径。

graph TD A[开始构建] --> B{是否加载 nvm?} B -- 否 --> C[无法找到 node/npm/pnpm] B -- 是 --> D[加载 Node.js 环境] D --> E[继续执行构建命令]

解决方法包括：

• 在 Jenkinsfile 中显式 source nvm.sh 文件。
• 使用 NVM_DIR 设置并加载 nvm。
• 使用 nvm use xx.x.x 切换到正确的 Node.js 版本。

4. 解决方案详解

以下是几种可行的解决方案，按照推荐顺序排列：

4.1 全局安装 pnpm 并配置 PATH

在 Jenkins 构建节点上以管理员身份全局安装 pnpm，并将其路径添加到系统 PATH 或 Jenkins 的环境变量中。

sudo npm install -g pnpm
export PATH=/usr/local/lib/node_modules/pnpm:$PATH

4.2 在 Jenkinsfile 中显式设置 PATH

如果你无法修改系统环境变量，可以在 Jenkinsfile 中显式指定 PATH：

env.PATH = "${env.HOME}/.npm-global/bin:${env.PATH}"

4.3 使用 npm exec pnpm 替代直接调用 pnpm

这是最推荐的做法之一，因为 npm exec 会自动查找并执行项目中的局部或全局安装的包。

npm exec pnpm run build

4.4 使用 nvm 加载 Node.js 环境

在 Jenkinsfile 的 pipeline 阶段中添加以下代码：

steps {
    sh 'export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"'
    sh 'nvm use 18'
    sh 'npm exec pnpm run build'
}

5. 最佳实践建议

为避免此类问题再次发生，建议遵循以下最佳实践：

1. 统一构建环境：使用 Docker 或 Jenkins Agent 统一构建环境。
2. 避免依赖全局安装：使用 npm exec 或 yarn dlx 等方式调用工具。
3. 自动化环境检查：在构建脚本中加入环境检测逻辑。
4. 定期清理缓存：Node_modules 和全局安装目录可能存在冲突。
5. 日志记录 PATH：在构建脚本中输出当前 PATH 值，便于排查。