MacOS下Jenkins执行npm命令提示not found的问题求助

一、自由风格项目的Groovy异常解决 #

你遇到的groovy.lang.MissingPropertyException是因为选错了构建步骤类型：

• 自由风格项目添加构建步骤时，必须选择「执行 shell」，而非「执行系统Groovy脚本」或其他Groovy相关选项。Groovy会把npm install当成变量调用，因此抛出异常。
• 修正PATH配置：homebrew安装的Node/npm在/opt/homebrew/bin目录下，而非/opt/homebrew，正确的shell脚本应为：

export PATH=/opt/homebrew/bin:$PATH
npm install

二、流水线项目npm找不到的解决 #

1. 确认NodeJS工具配置名称 #

进入「Manage Jenkins → Global Tool Configuration」，找到NodeJS安装项：

• 检查你配置的NodeJS实例名称是否为default，如果不是（比如命名为「NodeJS 20」），需修改流水线脚本中的工具名称：

tools {nodejs "NodeJS 20"} // 替换为你实际的配置名称

2. 解决Jenkins运行用户的环境问题 #

MacOS默认Jenkins以jenkins系统用户运行，而你本地安装的Node可能在个人用户的homebrew目录下，jenkins用户无访问权限：

• 本地测试方案：修改Jenkins运行用户为你的个人用户：
  1. 打开plist文件：sudo nano /Library/LaunchDaemons/org.jenkins-ci.plist
  2. 将<key>UserName</key>对应的<string>jenkins</string>改为你的用户名（比如yourname）
  3. 重启Jenkins服务：

     sudo launchctl unload /Library/LaunchDaemons/org.jenkins-ci.plist
     sudo launchctl load /Library/LaunchDaemons/org.jenkins-ci.plist
     

3. 手动指定PATH（工具配置不生效时） #

如果NodeJS工具配置仍无法注入环境变量，可在流水线脚本中直接指定PATH：

pipeline{
    agent any
    stages{
        stage('Build'){
            steps{
                git 'git@github.com:patebija/simple-node-js-react-npm-app.git'
                sh 'export PATH=/opt/homebrew/bin:$PATH && npm install'
            }
        }
    }
}

注意：流水线中必须用sh 'npm install'执行shell命令，直接写npm install会被Groovy解析为方法调用，导致异常。

三、排查辅助步骤 #

• 在Jenkins脚本控制台（Manage Jenkins → Script Console）执行println System.getenv('PATH')，查看Jenkins全局PATH是否包含Node目录。
• 在流水线中添加调试命令，查看构建时的环境：

sh 'echo $PATH'
sh 'which node'
sh 'which npm'

内容的提问来源于stack exchange，提问作者StackD