1. 为什么你的 mvn 命令总是“不被识别”
在 Windows 上折腾 Java 项目的人，几乎都遇到过这个经典报错：
mvn : 无法将“mvn”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。 请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。这个报错信息看起来简单，但它背后可能藏着五六种不同的原因。很多人第一反应是“环境变量没配好”，于是反复检查MAVEN_HOME和Path，改完重启终端，还是不行。然后开始怀疑人生，甚至重装系统。
我见过太多人在这一步卡住，尤其是刚接触 Maven 的开发者。Maven 本身是干嘛的？简单说，它是 Java 项目的构建和依赖管理工具。你写 Java 项目，不可能手动去下载几十个 jar 包然后一个个加到 classpath 里，Maven 帮你做这件事。它通过pom.xml文件描述项目需要哪些依赖，然后自动从仓库下载、管理版本、编译、打包、运行测试。没有 Maven，现代 Java 开发几乎寸步难行。
但 Maven 的安装和配置，恰恰是新手最容易翻车的地方。Windows 下的环境变量配置尤其如此，因为 Windows 的环境变量机制和 Linux/macOS 有本质区别，而且不同版本的 Windows 在界面和操作逻辑上也有差异。
这篇文章就是来解决这个问题的。我会从 Maven 的下载安装开始，一步步讲清楚环境变量配置的每一个细节，解释每一步为什么要这么做，然后重点分析mvn不被识别的各种原因和排查方法。无论你是刚学 Java 的新手，还是换了新电脑需要重新配置环境的老手，都能从这篇文章里找到可以直接抄作业的方案。
提示：本文所有操作基于 Windows 10/11 系统，Maven 3.9.x 版本，JDK 1.8 及以上。如果你用的是 Windows 7 或更早版本，部分界面路径可能略有不同，但核心逻辑完全一致。
2. Maven 安装前的准备工作
2.1 先确认 JDK 是否就绪
Maven 本身是 Java 写的，运行 Maven 需要 JDK 或 JRE。但注意，Maven 3.9.x 要求 JDK 8 及以上。如果你连 JDK 都没装好，那 Maven 肯定跑不起来。
检查 JDK 是否安装成功，打开命令提示符（CMD）或 PowerShell，输入：
java -version如果输出类似下面的内容，说明 JDK 已经就绪：
java version "1.8.0_381" Java(TM) SE Runtime Environment (build 1.8.0_381-b09) Java HotSpot(TM) 64-Bit Server VM (build 25.381-b09, mixed mode)如果提示'java' 不是内部或外部命令，那说明 JDK 的环境变量也没配好。这时候你需要先解决 JDK 的问题，再来看 Maven。JDK 的环境变量配置逻辑和 Maven 几乎一样，核心就是JAVA_HOME和Path两个变量。
我建议 JDK 和 Maven 都使用“解压版”而不是“安装版”。为什么？因为安装版会往系统里写注册表、往Program Files里塞文件，卸载不干净，而且路径里带空格（比如C:\Program Files\Java\jdk1.8.0_381），在某些脚本里容易出问题。解压版你放在D:\dev\jdk1.8这样的路径下，干净利落，想换版本直接改环境变量就行。
2.2 Maven 下载：官网和镜像怎么选
Maven 的官网是maven.apache.org，在首页就能找到 Download 链接。但官网下载速度在国内可能比较慢，尤其是下载apache-maven-3.9.x-bin.zip这种几十兆的文件时，有时候会卡住。
我的建议是：优先从官网下载，如果速度实在不行，可以找国内的开源镜像站。但要注意，镜像站的版本可能不是最新的，下载前确认一下版本号。另外，网上有些所谓的“maven 下载”页面其实是第三方打包的，里面可能夹带私货，尽量避开。
下载的时候选bin.zip而不是src.zip。bin是编译好的二进制版本，解压就能用；src是源码，需要自己编译，普通开发者完全不需要。
下载完成后，把 zip 包解压到一个你专门放开发工具的目录。我个人的习惯是D:\dev\下面放所有开发相关的工具：
D:\dev\ ├── jdk1.8\ ├── maven-3.9.6\ ├── git\ └── ...这样做的好处是路径短、无空格、好记。解压后 Maven 的目录结构大致如下：
D:\dev\maven-3.9.6\ ├── bin\ │ ├── mvn.cmd │ ├── mvn │ └── ... ├── boot\ ├── conf\ │ ├── settings.xml │ └── ... ├── lib\ └── ...其中bin目录下的mvn.cmd就是 Windows 下执行mvn命令时实际调用的脚本。环境变量配置的核心目的，就是让系统在任何路径下都能找到这个mvn.cmd。
2.3 目录命名的坑：空格和中文
这里要特别强调一个很多人忽略的问题：Maven 的安装路径里不要有空格和中文。
我见过有人把 Maven 解压到C:\Program Files\apache-maven-3.9.6，然后环境变量怎么配都不对。原因是Program Files中间有个空格，在某些脚本解析路径时会被截断。还有人放在D:\软件\maven这样的中文路径下，虽然 Windows 本身支持中文路径，但 Maven 的某些插件在处理路径时可能会出问题。
所以，安装路径最好是纯英文、无空格、层级不要太深。D:\dev\maven-3.9.6就是一个很好的选择。
3. 环境变量配置的完整实操流程
3.1 打开环境变量设置界面的正确姿势
Windows 下打开环境变量设置有好几种方式，我推荐最快的一种：
- 按下
Win + R，输入sysdm.cpl，回车。 - 在弹出的“系统属性”窗口中，点击“高级”选项卡。
- 点击右下角的“环境变量”按钮。
这样就直接打开了环境变量编辑窗口。窗口分上下两部分：上半部分是“用户变量”，只对当前用户生效；下半部分是“系统变量”，对所有用户生效。
注意：如果你只是自己用这台电脑，配“用户变量”就够了，不需要管理员权限。如果你希望所有用户都能用 Maven，或者某些 IDE 以服务方式运行时需要读取系统变量，那就配“系统变量”。我个人的习惯是配系统变量，避免以后换用户账户时又要重新配一遍。
3.2 新建 MAVEN_HOME 变量
在“系统变量”区域点击“新建”，弹出新建变量窗口：
- 变量名：
MAVEN_HOME - 变量值：
D:\dev\maven-3.9.6
这里的变量值就是你的 Maven 解压目录，注意不要带bin，也不要带末尾的反斜杠。有些人写成D:\dev\maven-3.9.6\bin，这是错的，会导致后续 Path 拼接出问题。
为什么要有MAVEN_HOME这个变量？因为 Maven 的某些脚本和工具会读取这个变量来定位 Maven 安装目录。虽然理论上你只在 Path 里加D:\dev\maven-3.9.6\bin也能让mvn命令生效，但配置MAVEN_HOME是更规范的做法，很多 IDE（比如 IntelliJ IDEA）在自动检测 Maven 时也会优先读这个变量。
3.3 编辑 Path 变量，把 bin 目录加进去
在“系统变量”区域找到Path变量，选中后点击“编辑”。在弹出的编辑窗口中，点击“新建”，然后输入：
%MAVEN_HOME%\bin这里用%MAVEN_HOME%而不是直接写死路径，好处是以后换 Maven 版本时，只需要改MAVEN_HOME的值，Path 不用动。
提示：在 Windows 10/11 的 Path 编辑界面里，每一行是一个路径。你可以用右侧的“上移”按钮调整顺序。Path 的查找是从上到下的，如果前面有同名的
mvn命令，后面的就不会生效。不过一般情况下不会有人装两个 Maven，所以顺序问题不大。
编辑完成后，一路点击“确定”保存。注意，每一层窗口都要点“确定”，不能直接关掉，否则修改不会生效。
3.4 验证配置：新开终端再测试
这是最关键的一步，也是最多人踩坑的地方。
修改环境变量后，必须重新打开一个新的命令提示符或 PowerShell 窗口，旧窗口不会自动加载新的环境变量。
很多人改完环境变量，直接在原来已经打开的 CMD 里输入mvn -v，发现还是报错，然后就开始怀疑自己是不是配错了。其实配置没问题，只是旧终端的环境变量还是旧的。
正确的验证步骤：
- 关闭所有已经打开的命令行窗口。
- 重新打开一个新的 CMD 或 PowerShell。
- 输入
mvn -v或mvn -version。
如果配置正确，你会看到类似下面的输出：
Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae) Maven home: D:\dev\maven-3.9.6 Java version: 1.8.0_381, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk1.8.0_381\jre Default locale: zh_CN, platform encoding: GBK OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"看到这个输出，说明 Maven 已经配置成功了。
4. mvn 不被识别的六大原因与排查方法
即使按照上面的步骤操作，还是有人会遇到mvn不被识别的问题。下面我把可能的原因逐一列出来，并给出排查方法。
4.1 原因一：Path 变量没生效或写错了
这是最常见的原因。排查方法：
在 CMD 中输入：
echo %Path%在 PowerShell 中输入：
$env:Path查看输出的内容里有没有D:\dev\maven-3.9.6\bin或%MAVEN_HOME%\bin展开后的路径。如果没有，说明 Path 没配好。
常见错误包括：
- 把路径加到了“用户变量”的 Path 里，但当前终端是以管理员身份运行的，管理员终端读取的是系统变量。
- Path 里写的是
%MAVEN_HOME%\bin，但MAVEN_HOME变量名拼错了，比如写成了MAVEN_HOM或MAVENHOME。 - Path 里直接写了
D:\dev\maven-3.9.6，漏掉了\bin。
4.2 原因二：MAVEN_HOME 变量值有误
在 CMD 中输入：
echo %MAVEN_HOME%如果输出为空，或者输出的路径不对，那就是MAVEN_HOME没配好。检查变量值是否指向了 Maven 的解压目录，而不是bin目录。
4.3 原因三：终端没有重启
前面已经强调过了，但这里再强调一次：改完环境变量，必须新开终端。我见过太多人在这上面浪费时间。
有一个简单的判断方法：如果你在旧终端里输入echo %MAVEN_HOME%输出为空，但在新终端里输出正常，那就说明是终端没重启的问题。
4.4 原因四：Maven 目录下没有 mvn.cmd
进入D:\dev\maven-3.9.6\bin目录，确认里面有没有mvn.cmd文件。如果下载的是src.zip并解压，bin目录下可能只有mvn（Linux/macOS 用的脚本）而没有mvn.cmd。Windows 下必须要有mvn.cmd才能执行。
另外，有些杀毒软件可能会误删mvn.cmd，检查一下杀毒软件的隔离区。
4.5 原因五：Path 中有冲突的同名命令
如果你之前装过其他版本的 Maven，或者装过 Gradle 等构建工具，Path 里可能有多个包含mvn的路径。Windows 会按 Path 的顺序查找，找到第一个就停止。如果第一个路径里的mvn有问题，后面的就不会被使用。
排查方法：在 CMD 中输入：
where mvn这个命令会列出所有能找到的mvn命令的完整路径。如果输出的第一个路径不是你期望的 Maven 路径，那就需要调整 Path 顺序，或者删除旧的路径。
4.6 原因六：PowerShell 的执行策略限制
在 PowerShell 中，有时候即使 Path 配好了，mvn命令也可能因为执行策略（Execution Policy）的限制而无法运行。虽然mvn.cmd是批处理文件，一般不受 PowerShell 执行策略影响，但如果你用的是mvn.ps1之类的脚本，就可能被拦截。
排查方法：在 PowerShell 中输入：
Get-ExecutionPolicy如果输出是Restricted，可以尝试改为RemoteSigned：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser不过对于mvn.cmd来说，这个问题比较少见。如果你在 CMD 里能正常运行mvn，但在 PowerShell 里不行，那可能是 PowerShell 的配置文件或别名有问题。
5. Maven 配置优化与常见问题
5.1 配置阿里云镜像加速依赖下载
Maven 默认从国外的中央仓库下载依赖，国内访问速度很慢，有时候还会超时。配置阿里云镜像可以大幅提升下载速度。
打开 Maven 安装目录下的conf\settings.xml文件，找到<mirrors>标签，在里面添加：
<mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>保存后，Maven 下载依赖时会优先从阿里云仓库拉取，速度会有明显提升。
注意：
settings.xml文件里可能已经有一些注释掉的 mirror 配置，不要直接删掉，在<mirrors>标签内新增即可。另外，mirrorOf写*表示所有仓库都走这个镜像，包括插件仓库。如果你有特殊需求，可以改成central只镜像中央仓库。
5.2 修改本地仓库位置
Maven 默认把下载的依赖放在C:\Users\你的用户名\.m2\repository目录下。这个目录会随着项目增多越来越大，可能占用几个 GB 的 C 盘空间。建议改到其他盘。
在settings.xml中找到<localRepository>标签，取消注释并修改：
<localRepository>D:\dev\maven-repo</localRepository>这样依赖就会下载到D:\dev\maven-repo目录下。
5.3 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
mvn不是内部或外部命令 | Path 未配置或未生效 | 检查 Path 是否包含%MAVEN_HOME%\bin，新开终端 |
mvn -v输出 Java 版本不对 | JAVA_HOME指向了错误的 JDK | 检查JAVA_HOME变量值 |
| 依赖下载极慢或超时 | 未配置国内镜像 | 在settings.xml中配置阿里云镜像 |
mvn clean compile报编译错误 | JDK 版本与项目不匹配 | 检查pom.xml中的maven.compiler.source和target |
| C 盘空间被占满 | 本地仓库在默认位置 | 修改settings.xml中的localRepository |
PowerShell 中mvn可用但 CMD 中不可用 | 用户变量和系统变量不一致 | 统一配置到系统变量，或检查用户变量 |
5.4 实操心得：我踩过的那些坑
第一个坑是路径里的空格。我早期把 Maven 放在C:\Program Files\下面，结果mvn命令时好时坏。后来才知道是空格导致脚本解析路径时出了问题。从那以后，所有开发工具我都放在D:\dev\下面，再也没遇到过类似问题。
第二个坑是环境变量改了但没重启终端。这个坑我踩过不止一次，每次都是改完变量直接在当前终端测试，然后发现不生效，又回去检查配置，浪费了大量时间。现在我养成了一个习惯：改完环境变量，先关掉所有终端，再重新打开一个，第一步就是echo %MAVEN_HOME%确认变量生效。
第三个坑是多个 JDK 版本冲突。我电脑上装过 JDK 8、JDK 11 和 JDK 17，JAVA_HOME指向不同版本时，Maven 的行为会不一样。有些老项目用 JDK 8 编译，有些新项目用 JDK 17，切换起来很麻烦。后来我用了一个小技巧：在项目根目录下放一个.mvn\jvm.config文件，里面指定-Dmaven.compiler.source=8之类的参数，这样就不用频繁改全局的JAVA_HOME了。
第四个坑是**settings.xml文件的位置**。Maven 会读取两个位置的settings.xml：一个是全局的conf\settings.xml，一个是用户目录下的.m2\settings.xml。用户目录下的配置会覆盖全局配置。如果你改了全局配置但不生效，检查一下用户目录下是不是也有一个settings.xml。
6. 从 mvn 报错延伸出去的环境变量通用排查思路
mvn不被识别这个问题，本质上是一个环境变量配置问题。同样的排查思路可以应用到其他命令行工具上，比如git、node、npm、python等。
核心逻辑就三步：
- 确认工具的可执行文件在哪里。比如
mvn.cmd在D:\dev\maven-3.9.6\bin目录下。 - 确认这个目录在 Path 变量里。用
echo %Path%或$env:Path查看。 - 确认终端加载了最新的环境变量。新开终端，或者用
refreshenv命令（需要安装 Chocolatey 才有）。
如果这三步都确认了还是不行，那就用where命令（CMD）或Get-Command（PowerShell）来查找系统实际找到的命令路径，对比是否和你期望的一致。
还有一个容易被忽略的点：环境变量的作用域。Windows 有用户变量和系统变量两套，用户变量会覆盖同名的系统变量。如果你在用户变量里配了一个错误的MAVEN_HOME，系统变量里配了正确的，最终生效的是用户变量里的错误值。排查的时候两边都要看。
另外，某些 IDE（比如 IntelliJ IDEA）有自己的环境变量配置，不一定会继承系统的环境变量。如果你在终端里mvn能用，但在 IDEA 的 Terminal 里不能用，检查一下 IDEA 的设置里有没有覆盖环境变量。
最后再分享一个小技巧：如果你经常需要在不同版本的 Maven 之间切换，可以写一个简单的批处理脚本，比如mvn-use-3.9.6.bat，内容就是设置MAVEN_HOME并更新 Path，然后启动一个新的 CMD 窗口。这样切换版本只需要双击对应的脚本，不用每次都去改系统环境变量。
