Windows 下升级 Maven 3.6.1 到 3.9.9 踩坑全记录

📌 问题场景

在 Maven 多模块 Spring Boot 项目打包时，突然报错：

复制代码

Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.14.0:compile
The plugin requires Maven version 3.6.3

检查一下自己的 Maven 版本：

复制代码

mvn --version
# Apache Maven 3.6.1

好家伙，2019 年的老古董，确实该升级了。

第一步：下载解压，以为完事了

去 Maven 官网下载 3.9.9 版本，解压到 E:\JavaWeb_study\apache-maven-3.9.9。

打开终端一跑 ------ 还是 3.6.1。

于是就开始了漫长的环境变量排查之路......

第二步：肉眼翻环境变量，翻了个寂寞

Win + R → sysdm.cpl → 高级 → 环境变量：

上半部分（用户变量） ：Path 里没有 Maven 路径
下半部分（系统变量）：挤得满满当当，用眼睛一个一个字地扫，愣是没找到

这时候改用命令行查，一行就定位了：

复制代码

# 精确找到 mvn 命令的来源
Get-Command mvn | Select-Object Source

# 输出：E:\JavaWeb_study\apache-maven-3.6.1-bin\apache-maven-3.6.1\bin\mvn.cmd

再查环境变量：

复制代码

# 查系统变量中的 MAVEN_HOME
[Environment]::GetEnvironmentVariable('MAVEN_HOME', 'Machine')
# 输出：E:\JavaWeb_study\apache-maven-3.6.1-bin\apache-maven-3.6.1

# 查系统 PATH 中包含 maven 的条目
[Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';' | Select-String maven
# 输出：E:\JavaWeb_study\apache-maven-3.6.1-bin\apache-maven-3.6.1\bin

真相大白 ：旧 Maven 同时藏在系统 Path 和系统 MAVEN_HOME 里，GUI 里路径太长根本看不见。

第三步：改 PATH 以为搞定了，结果白改

先用普通权限把新路径加到用户 PATH：

复制代码

[Environment]::SetEnvironmentVariable('Path', '新路径;' + $oldPath, 'User')

又把用户变量 MAVEN_HOME 改成新路径：

复制代码

[Environment]::SetEnvironmentVariable('MAVEN_HOME', 'E:\JavaWeb_study\apache-maven-3.9.9', 'User')

关掉终端重新打开，mvn --version ------ 还是 3.6.1 😡

第四步：定位根因------系统变量 vs 用户变量的优先级

排查后发现问题所在：

变量	作用域	值	状态
`MAVEN_HOME`	用户变量	`...apache-maven-3.9.9`	✅ 已改
`MAVEN_HOME`	系统变量	`...apache-maven-3.6.1`	❌ 还是旧的
`Path`	用户变量	开头已加 3.9.9	✅
`Path`	系统变量	中间夹着 3.6.1	❌

核心知识点：

系统变量的优先级 ≥ 用户变量 。即使你改了用户变量，只要系统变量里有同名条目，系统变量会覆盖它。而且修改系统变量必须管理员权限，普通 PowerShell 改不动。

另外，Maven 的 mvn.cmd 启动脚本内部靠 MAVEN_HOME 变量定位核心库，不修改 MAVEN_HOME，光改 Path 是没用的。

第五步：终极修复（管理员权限）

右键 "命令提示符" → "以管理员身份运行"，执行以下命令：

复制代码

:: 1. 把系统级 MAVEN_HOME 指向新版本
setx MAVEN_HOME "E:\JavaWeb_study\apache-maven-3.9.9" /M

:: 2. 从系统 Path 中删除旧 Maven 路径（PowerShell 命令）
powershell -Command "$p=[Environment]::GetEnvironmentVariable('Path','Machine');$p=$p -replace 'E:\\JavaWeb_study\\apache-maven-3.6.1-bin\\apache-maven-3.6.1\\bin;?','';[Environment]::SetEnvironmentVariable('Path',$p,'Machine')"

参数说明：

/M 参数表示写入系统变量（Machine）
-replace 用正则把旧路径从 PATH 中移除

关掉所有终端，重新打开验证：

复制代码

mvn --version
# Apache Maven 3.9.9 ✅

总结：一张图搞清楚 Windows 环境变量

复制代码

┌─────────────────────────────────────────────┐
│          Windows 环境变量层级                │
├─────────────────────────────────────────────┤
│  用户变量（User）                            │
│  ├── 优先级：低                              │
│  ├── 修改权限：普通用户即可                   │
│  └── 作用范围：仅当前用户                     │
│                                              │
│  系统变量（Machine）   ← 优先级更高！         │
│  ├── 优先级：高（覆盖同名用户变量）            │
│  ├── 修改权限：需要管理员                    │
│  └── 作用范围：所有用户                       │
└─────────────────────────────────────────────┘

几个实用的排查命令（收藏备用）

复制代码

# 查某个命令的实际位置
Get-Command mvn | Select-Object Source

# 查指定变量（User / Machine）
[Environment]::GetEnvironmentVariable('MAVEN_HOME', 'User')
[Environment]::GetEnvironmentVariable('MAVEN_HOME', 'Machine')

# 从长 PATH 中过滤关键字
[Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';' | Select-String java

# 设置用户变量
setx 变量名 "值"

# 设置系统变量（需管理员）
setx 变量名 "值" /M

后记

这个问题本质上不难，但坑在两点：

Windows 环境变量编辑器太难用 ，PATH 长的时候完全没法翻，命令行查比 GUI 快十倍；
系统变量 vs 用户变量的优先级，不搞清楚的话改了白改。

希望这篇踩坑记录能帮你少走弯路 ✌️