Maven 3.9.5安装后执行mvn -v报错“JAVA_HOME not found”？

Question

Maven 3.9.5 安装后执行 `mvn -v` 报错 “JAVA_HOME not found”，是典型环境变量配置缺失问题。Maven 3.9+（尤其3.9.2起）强化了对 `JAVA_HOME` 的强制校验，不再兼容仅依赖 `PATH` 中的 Java 可执行文件。常见原因包括：① 未设置 `JAVA_HOME` 环境变量；② 已设置但路径指向 JRE 而非 JDK（需包含 `/bin/javac`）；③ 变量名大小写错误（如 `java_home`）、Shell 配置未生效（`.bashrc`/`.zshrc` 未 source 或未重启终端）；④ Windows 下系统变量与用户变量冲突或路径含空格未加引号。验证方法：终端执行 `echo $JAVA_HOME`（Linux/macOS）或 `echo %JAVA_HOME%`（Windows），再确认该路径下存在 `bin/java` 和 `bin/javac`。注意：Maven 3.9.5 不再自动探测 `java` 命令位置，必须显式配置正确 JDK 路径。

Answer 1

```html

一、现象层：错误表征与版本敏感性

执行 mvn -v 时抛出 "JAVA_HOME not found"，表面是环境变量缺失，实则是 Maven 3.9.5 的架构级行为变更——自 3.9.2 起，maven-wrapper 和 mvn 启动脚本彻底移除了对 PATH 中 java 命令的 fallback 探测逻辑。这意味着：即使 java -version 正常返回，Maven 仍会拒绝启动。

二、根因层：四大典型失效模式

• ① 完全未定义 JAVA_HOME：尤其常见于 CI/CD 容器镜像或新装 macOS/Linux 环境；
• ② JDK/JRE 混淆：路径指向 /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home（macOS JRE）或 C:\Program Files\Java\jre1.8.0_381（Windows JRE），缺少 javac；
• ③ Shell 作用域污染：在 .bashrc 中设置但未执行 source ~/.bashrc，或终端以 login shell 启动却配置在 non-login shell 文件中；
• ④ Windows 路径语义陷阱：含空格路径（如 C:\Program Files\Java\jdk-17.0.2）未用双引号包裹，导致批处理解析截断。

三、验证层：精准诊断流程图

graph TD A[执行 mvn -v 报错] --> B{echo $JAVA_HOME
或 echo %JAVA_HOME%} B -->|为空| C[未定义变量 → 检查配置文件] B -->|非空| D[ls $JAVA_HOME/bin/java
ls $JAVA_HOME/bin/javac] D -->|任一不存在| E[路径指向 JRE 或损坏 JDK] D -->|均存在| F[检查 shell 加载顺序
或 Windows 变量作用域]

四、解决方案层：跨平台标准化配置

平台	推荐配置位置	关键语法示例	生效命令
Linux/macOS	~/.zshrc（Zsh 默认）或 ~/.bash_profile	export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64	source ~/.zshrc
Windows	系统属性 → 高级 → 环境变量 → 系统变量	JAVA_HOME = "C:\Program Files\Java\jdk-17.0.2"（含引号！）	重启 CMD/PowerShell

五、进阶层：企业级健壮性实践

对于 DevOps 流水线或多 JDK 共存场景，建议采用：
✅ 使用 update-alternatives --config java（Linux）统一管理 JDK 符号链接；
✅ 在 ~/.mavenrc 中添加 export MAVEN_OPTS="-Dfile.encoding=UTF-8"，避免隐式依赖；
✅ 通过 mvn -X -e 开启 debug 日志，定位 org.apache.maven.cli.MavenCli 初始化阶段失败堆栈；
✅ 在 Jenkins Pipeline 中显式声明 withEnv(['JAVA_HOME=/opt/java/jdk17'])，规避 agent 全局配置漂移。

六、避坑层：高频反模式清单

1. 误将 JAVA_HOME 设为 /usr/bin/java（这是符号链接，非 JDK 根目录）；
2. 在 Windows 中同时设置用户变量和系统变量且值不一致，导致 Maven 读取到空值；
3. macOS 使用 Homebrew 安装 OpenJDK 后，路径为 /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home，而非传统 /usr/libexec/java_home -v17 返回路径；
4. IDE（如 IntelliJ）内嵌 Maven 与终端 Maven 环境分离，调试时需确认终端复现问题；
5. 容器化部署时未挂载 JDK，仅靠 apt-get install default-jdk 无法保证 JAVA_HOME 自动设置。

七、验证黄金标准

执行以下三步验证链，缺一不可：
echo $JAVA_HOME && ls -l $JAVA_HOME/bin/java $JAVA_HOME/bin/javac && java -version && javac -version && mvn -v
输出应显示 JDK 版本号（非 JRE）、javac 存在、且 Maven 显示 Apache Maven 3.9.5 及对应 JDK 路径。

```