配置Maven及Jenkins后构建仍提示'mvn'不是内部或外部命令如何解决

本地命令行执行mvn正常，仅Jenkins构建时提示'mvn' is not recognized，核心原因是Jenkins构建进程的运行上下文，没有拿到Maven的可执行文件路径，和你本地交互登录的环境是隔离的，常见触发场景：

• 环境变量配置范围错误：Maven相关变量配到了当前登录用户的用户变量，而非系统变量；配置完环境变量后没有重启Jenkins服务，进程仍持有启动时加载的旧环境变量缓存。
• Jenkins配置错误：全局工具中Maven路径配置错误，或者构建任务中没有选中正确配置的Maven实例，直接调用系统命令时找不到对应可执行文件。
• 服务运行身份隔离：Jenkins以Windows服务形式运行时，使用的服务账户和你当前登录桌面的账户不是同一个，账户间的环境变量、权限不互通。

按以下顺序操作即可定位修复：

1. 修正环境变量配置范围
   打开Windows系统环境变量设置面板，将MAVEN_HOME（或M2_HOME）配置到系统变量区块（不是当前用户的用户变量区块），变量值为Maven安装根目录（例如C:\tools\apache-maven-3.9.8，不要定位到bin子目录）；随后编辑系统变量下的Path条目，新增%MAVEN_HOME%\bin，移除用户变量下重复配置的Maven路径。
2. 重启Jenkins服务生效配置
   按下Win+R输入services.msc打开Windows服务管理器，找到名称为Jenkins的服务，右键选择「重启」。注意不要只在Jenkins网页端点击「重载配置」，该操作不会刷新服务进程的环境变量缓存。
3. 验证Jenkins进程的环境变量读取情况
   新建一个临时自由风格测试任务，添加「执行Windows批处理命令」构建步骤，输入以下命令：

   echo MAVEN_HOME: %MAVEN_HOME%
   where mvn
   

   执行该任务查看控制台输出：
   • 如果MAVEN_HOME输出为空，或where mvn提示找不到文件，回到第一步检查系统变量配置，确认Jenkins服务已完成重启。
   • 如果where mvn能正常返回mvn.exe的完整绝对路径，说明环境变量配置已生效，继续下一步检查Jenkins工具配置。
4. 核对全局Maven工具配置
   进入Jenkins管理后台的「全局工具配置」页面，找到Maven配置区块：
   • 本地手动安装的Maven不要勾选「自动安装」选项，Maven安装路径填入和系统变量MAVEN_HOME完全一致的绝对路径，不要指向bin子目录。
   • 记录该Maven配置项的自定义名称（例如Maven-3.9.8）。
5. 修正构建任务的调用配置
   打开报错构建任务的配置页：
   • 如果使用「Invoke top-level Maven targets」作为构建步骤，Maven版本下拉选项必须选中上一步配置好的Maven实例，不要选择「Default」选项。
   • 如果是自定义批处理脚本调用mvn命令，建议替换为Jenkins内置的Maven构建步骤，或直接写mvn.exe的完整绝对路径调用（例如"C:\tools\apache-maven-3.9.8\bin\mvn.exe" install），避免依赖Path变量搜索。
6. 特殊场景兜底检查
   如果Jenkins服务配置了自定义运行账户（非默认Local System账户），要么将Maven环境变量配置到该运行账户的用户变量下，要么临时将服务运行账户切为本地系统账户测试，排除账户环境隔离的问题。

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