Mac系统Jenkins构建作业报错：docker: command not found

问题原因 #

Jenkins的Docker代理功能需要主节点能直接执行docker命令，但MacOS上docker默认安装在/usr/local/bin，而Jenkins进程的环境变量PATH未包含该路径。直接将PATH替换为/usr/local/bin会丢失系统默认路径（如/bin、/usr/bin），导致sh等基础命令无法找到。

解决方案 #

方案1：在Jenkins全局配置中追加PATH（推荐） #

不要直接替换PATH，而是在原有路径基础上追加/usr/local/bin：

1. 进入Jenkins后台，点击Manage Jenkins > Configure System
2. 找到Global properties区域，勾选Environment variables
3. 添加环境变量：
   • 变量名：PATH
   • 变量值：${PATH}:/usr/local/bin
4. 保存配置，重启Jenkins服务

方案2：修改Jenkins启动配置文件 #

根据你的Jenkins安装方式调整启动参数，确保启动时包含完整的PATH：

• Homebrew安装的Jenkins：
  1. 编辑启动配置文件：/usr/local/opt/jenkins/homebrew.mxcl.jenkins.plist
  2. 在<array>标签内添加一行：

     <string>--env=PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
     

  3. 重启Jenkins：brew services restart jenkins
• PKG安装的Jenkins：
  1. 编辑启动配置文件：/Library/LaunchDaemons/org.jenkins-ci.plist
  2. 找到<key>EnvironmentVariables</key>，添加完整的PATH配置：

     <key>EnvironmentVariables</key>
     <dict>
         <key>PATH</key>
         <string>/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
     </dict>
     

  3. 重启Jenkins：

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

验证配置 #

运行以下流水线确认PATH和docker命令正常：

pipeline {
    agent any
    stages {
        stage('Verify Configuration') {
            steps {
                sh 'echo $PATH'
                sh 'docker --version'
            }
        }
    }
}

如果能正常输出docker版本，再执行你的Docker代理流水线即可正常运行。

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