Jenkins Agent执行Shell任务时无法识别Maven、Gradle如何解决？

根因说明 #

1. Jenkins Agent启动时默认使用非登录、非交互式shell，不会主动加载用户目录下的~/.profile配置，因此写在该文件里的工具路径默认不会被Jenkins任务识别。
2. JDK的Tool Locations配置是Jenkins的原生特殊逻辑，配置后会自动将对应JDK的bin目录注入到任务的PATH环境变量中，因此Java命令可以正常识别；但Maven、Gradle的Tool Locations没有自动注入PATH的默认逻辑，仅配置该参数不会让Jenkins任务自动找到对应命令。

可行解决方案 #

方案1：单任务快速适配（无需修改全局配置） #

在Execute shell步骤的第一行添加以下任意一行代码即可：

• 加载你已配置好的用户环境变量：source ~/.profile
• 直接手动追加工具路径到当前任务的PATH：export PATH=/opt/apache/maven/3.8.2/bin:/opt/gradle/7.2/bin:$PATH

方案2：全局工具配置管控（推荐，适合多Agent、多版本管理场景） #

1. 登录Jenkins Controller，进入「系统管理 - 全局工具配置」页面
2. 新增Maven配置：自定义名称（例如Maven-3.8.2），取消「自动安装」勾选，保存
3. 新增Gradle配置：自定义名称（例如Gradle-7.2），取消「自动安装」勾选，保存
4. 回到Agent节点配置页面，在「Node Properties - Tool Locations」中，分别选中刚才创建的Maven、Gradle名称，填写Agent上的工具根目录（注意不需要到bin目录）：
   • Maven根目录：/opt/apache/maven/3.8.2
   • Gradle根目录：/opt/gradle/7.2
5. 任务调用时按场景选择：
   • 用Freestyle内置Maven/Gradle步骤：直接选择对应配置的工具版本即可正常执行
   • 用自定义Shell步骤：先通过tool指令获取工具路径后注入PATH，示例如下：

     // Pipeline 示例
     def mvnHome = tool 'Maven-3.8.2'
     def gradleHome = tool 'Gradle-7.2'
     sh "export PATH=${mvnHome}/bin:${gradleHome}/bin:\$PATH && mvn clean package"
     

方案3：Agent全局永久生效（无需调整Jenkins侧配置） #

直接将工具路径写入Agent的系统级环境变量配置，所有Jenkins任务自动生效：

1. 编辑Agent的/etc/environment文件，在PATH变量的值末尾追加工具bin目录，修改后示例：

   PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/opt/java/openjdk/jdk-11.0.12+7/bin:/opt/apache/maven/3.8.2/bin:/opt/gradle/7.2/bin"
   

2. 执行source /etc/environment使配置生效，重启Jenkins Agent进程即可。

验证方法 #

修改配置后，在任务的Execute shell中添加以下测试命令：

echo $PATH
which mvn
which gradle

执行任务后查看输出，确认PATH包含对应工具的bin目录、which命令返回的路径和你本地终端查询到的路径一致即可。

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