Jenkins 构建时提示 mvn: not found，本质是环境变量未正确继承、Maven 未在 Jenkins 运行上下文中可用；本文提供从系统级安装、路径配置、Jenkins 工具管理到流水线最佳实践的全链路解决指南。

jenkins 构建时提示 mvn: not found，本质是环境变量未正确继承、maven 未在 jenkins 运行上下文中可用；本文提供从系统级安装、路径配置、jenkins 工具管理到流水线最佳实践的全链路解决指南。

在将 Java 升级至 JDK 17 后（如 Raspberry Pi 上手动解压安装 Temurin JDK），许多用户会遇到 Jenkins 无法识别 mvn 命令的问题——即使终端中 mvn -v 正常执行，Jenkins 构建却报错 command execution failed: java.io.IOException: Cannot run program "mvn"。根本原因在于：Jenkins（尤其是以 jenkins 用户或 SYSTEM 身份运行的守护进程）并不自动继承 pi 用户的 shell 环境变量（如 $PATH、$MAVEN_HOME），且其子进程默认不加载 .bashrc 或 .profile。

✅ 正确做法：通过 Jenkins 全局工具配置管理 Maven（推荐）

这是最稳定、可移植、符合 CI/CD 最佳实践的方式，完全规避手动配置环境变量的风险：

1. 进入 Jenkins 管理界面 → 系统管理 > 全局工具配置

2. 在 Maven 区域点击 新增 Maven

3. 填写名称（如 maven-3.9.4），取消勾选 “自动安装”（因你已手动部署）

4. 在 MAVEN_HOME 中填写绝对路径：

   

   Java Maven Common

   Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

   下载

   /opt/maven

   ✅ 注意：此处填 MAVEN_HOME 路径，不是 bin 目录；Jenkins 会自动将其 bin 子目录加入构建环境的 PATH。

5. 保存配置

6. 在流水线（Jenkinsfile）或自由风格项目中显式声明工具：

   pipeline {
       agent any
       tools {
           jdk 'temurin-17.0.1'   // 对应已配置的 JDK 名称
           maven 'maven-3.9.4'     // 对应上一步配置的 Maven 名称
       }
       stages {
           stage('Build') {
               steps {
                   sh 'mvn -version'  // ✅ 此时可正常执行
                   sh 'mvn clean package -DskipTests'
               }
           }
       }
   }

⚠️ 若必须在 Shell 中临时调用（不推荐用于生产）

若暂未迁移至声明式流水线，可在构建步骤中显式指定 mvn 全路径并确保权限可执行：

# 检查权限（确保 jenkins 用户可读可执行）
ls -l /opt/maven/bin/mvn
# 如需授权（在容器或主机中执行）：
sudo chmod +x /opt/maven/bin/mvn

# Jenkins 构建脚本中使用全路径
/opt/maven/bin/mvn -version
/opt/maven/bin/mvn clean install

? 关键验证点（排查必做）

检查项	命令	预期结果
Jenkins 进程实际用户	ps aux \| grep jenkins	应为 jenkins 用户（非 pi）
jenkins 用户能否访问 Maven	sudo -u jenkins /opt/maven/bin/mvn -v	必须成功输出版本信息
PATH 是否包含 Maven bin	sudo -u jenkins echo $PATH	输出中应含 /opt/maven/bin
Jenkins 环境变量是否生效	新建任务 → 执行 shell：env \| grep -i maven	应显示 MAVEN_HOME=/opt/maven

? 重要注意事项

• 不要依赖用户级环境变量：Jenkins 服务通常以独立用户（如 jenkins）启动，不会加载 pi 的 ~/.bashrc。.profile 也仅对登录 shell 生效，而 Jenkins 使用非交互式 shell。
• 避免在容器中 apt-get install maven 后不重启 Jenkins：Docker 容器内安装后需重启 Jenkins 服务或容器，否则新 PATH 不生效。
• Java 17 兼容性确认：确保所用 Maven 版本 ≥ 3.8.1（官方支持 JDK 17）。Maven 3.9.4 完全兼容，无需降级。
• 离线环境建议：若为内网/离线部署（如 Raspberry Pi），请提前下载 Apache Maven 3.9.4 binary zip，解压至 /opt/maven 并设置权限：

  sudo chown -R jenkins:jenkins /opt/maven
  sudo chmod -R 755 /opt/maven

✅ 总结

mvn: not found 不是 Maven 安装失败，而是 Jenkins 运行环境与用户环境隔离所致。唯一健壮解法是放弃全局 PATH 注入，转而使用 Jenkins 内置的“全局工具配置”机制——它确保每次构建都在纯净、可复现的环境中加载指定版本的 JDK 和 Maven，同时天然支持多版本共存、跨节点一致性及流水线即代码（Pipeline as Code）演进。升级 JDK 17 后，只需同步配置对应 Maven 工具，即可无缝支撑 Spring Boot 3.x 等现代 Java 栈构建需求。