Hermes Agent是一款自动化构建与部署场景中常用的代理工具，它在执行任务时往往依赖本地的Maven环境来编译打包Java项目。不少使用者在启动Hermes Agent时会遇到类似mvn不是内部或外部命令、Cannot find mvn executable或者Maven home not set的报错，追根溯源基本都是Maven环境变量配置出了问题。本文将从报错原因、Windows与Linux下的配置步骤、验证方法以及常见坑点几个方面，给出一份完整可操作的解决指南。
一、为什么Hermes Agent会报Maven相关的错误
Hermes Agent在接到构建任务后，会通过系统命令的方式调用mvn命令来执行编译。而调用mvn的前提是操作系统能够通过环境变量Path找到Maven的可执行文件。如果系统根本没有安装Maven，或者安装了但环境变量没有配置，操作系统就会抛出命令找不到的错误。
典型的报错信息包括以下几种：Windows下通常是'mvn' 不是内部或外部命令，也不是可运行的程序；Linux或macOS下则是bash: mvn: command not found；还有一种情况是能找到mvn命令，但执行时报The JAVA_HOME environment variable is not defined correctly，这说明Maven本身找到了，但它依赖的Java环境又出了问题。Maven本质上是跑在JVM上的Java程序，mvn脚本只是负责启动JVM，所以Maven与JDK的配置需要一起检查，缺一不可。
另外要提醒一点，有些用户在命令行里手动执行mvn是正常的，但Hermes Agent仍然报错。这通常是因为Hermes Agent是以系统服务方式运行的，服务进程读取的环境变量可能与当前用户会话不同，尤其是在Windows下用不同账号安装服务时很容易踩到这个坑。这类情况后面会专门说明处理办法。
二、Windows系统下Maven环境变量的正确配置
第一步当然是先下载并解压Maven。建议到Apache Maven官网下载二进制压缩包，解压到一个纯英文、无空格的目录，比如C:\apache-maven-3.9.6。切记不要放在C:\Program Files这种带空格的路径下，也不要放在中文目录里，否则脚本解析路径时可能出现诡异问题。
第二步配置MAVEN_HOME。右键点击此电脑，选择属性，进入高级系统设置，点击环境变量按钮。在系统变量区域点击新建，变量名填MAVEN_HOME，变量值填Maven的解压目录，例如C:\apache-maven-3.9.6。注意这里填的是Maven的根目录，也就是能看到bin、conf、lib子文件夹的那一层，不要一路点到bin里面去。
第三步配置Path。在系统变量列表中找到Path，点击编辑，新增一条记录，内容写成%MAVEN_HOME%\bin。使用变量引用的好处是以后升级Maven版本时只需要改MAVEN_HOME的值，Path不用动。也可以在命令行里快速验证配置是否符合预期：
echo %MAVEN_HOME% echo %Path% where mvn
第四步确认JAVA_HOME。Maven离不开JDK，请确保系统中已经配置了JAVA_HOME变量指向JDK根目录，并且Path中包含%JAVA_HOME%\bin。如果机器上装了多个JDK，要确认JAVA_HOME指向的版本满足Hermes Agent的要求，一般建议使用JDK 8或以上版本。
配置完成之后，务必重新打开一个命令行窗口再执行mvn -v。环境变量的修改不会自动同步到已经打开的旧窗口，很多人配置明明是对的，却在旧窗口里反复测试失败，白白浪费时间。正常的输出会同时打印出Maven版本和Java版本信息，两条都正确显示才算配置成功。
三、Linux系统下的配置方式与注意事项
Linux下的配置思路类似，只是操作方式从图形界面变成了编辑配置文件。假设Maven解压在/opt/apache-maven-3.9.6目录下，编辑当前用户的配置文件，比如~/.bashrc或者/etc/profile，在末尾追加以下内容：
export MAVEN_HOME=/opt/apache-maven-3.9.6 export PATH=$PATH:$MAVEN_HOME/bin export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 export PATH=$PATH:$JAVA_HOME/bin
保存退出后执行source ~/.bashrc让配置立即生效，然后运行mvn -v验证。如果提示权限不足，记得先给mvn脚本加上可执行权限：chmod +x $MAVEN_HOME/bin/mvn。
这里有一个Linux环境特有的坑需要特别注意。如果Hermes Agent是通过systemd服务或者以非交互式shell方式启动的，它不会加载~/.bashrc，因此也就读不到你配置的环境变量。解决办法有两种：一是把配置写到/etc/profile.d/maven.sh中并确保所有用户可读，二是在systemd的服务单元文件里显式声明环境变量，例如：
[Service] Environment="MAVEN_HOME=/opt/apache-maven-3.9.6" Environment="PATH=/opt/apache-maven-3.9.6/bin:/usr/lib/jvm/java-8/bin:/usr/bin:/bin"
修改完服务单元后执行systemctl daemon-reload再重启Hermes Agent服务即可。
四、常见踩坑点与排查思路
配置环境变量看似简单，但实际排查中发现大量报错都集中在几个反复出现的问题上。第一个是变量值填错层级，MAVEN_HOME误指向了bin目录，导致拼接出来的路径变成C:\apache-maven-3.9.6\bin\bin，系统自然找不到mvn。第二个是JDK与Maven版本不匹配，比如用很老的项目搭配最新版Maven，可能报Unsupported major.minor version之类的错误，解决办法是让两者版本保持兼容。
第三个是多版本Maven冲突。机器上既装了IDE自带的Maven，又手动解压了一份，Path中两条记录指向不同位置，实际生效的是排在前面的那条。可以用where mvn（Windows）或which mvn（Linux）确认当前生效的到底是哪一个，必要时把Path中多余的条目删掉或者调整顺序。
第四个是服务账号环境隔离。前面提到过，Windows下如果Hermes Agent服务是用Local System账号运行的，它读不到你在自己用户账号下配置的用户级环境变量。解决办法是把环境变量配置到系统变量区域而不是用户变量区域，或者修改服务运行的账号，配置完成后重启服务让新环境生效。
最后建议养成一个习惯：每次修改环境变量后，都用mvn -v做一次完整验证，确认输出的Maven home路径、Java version和Java home路径都符合预期，再回到Hermes Agent中重试任务。按照上面这套流程走下来，绝大多数因Maven环境变量引起的Hermes Agent报错都能得到彻底解决。
Hermes AgentMaven环境变量配置MAVEN_HOME修改时间：2026-09-06 18:18:32