直接开干。先在 Windows 上装 Maven 这件事，看起来就是一个下载、解压、配环境变量的流程，但几乎每隔几天就能在论坛上看到有人卡住。而且卡住的地方往往不是 Maven 本身，是 Windows 的环境、IDEA 的集成、还有仓库下载慢这三座大山在互相拉扯。
这篇就基于我在 Windows 10 / Windows 11 上从零配置 Maven 并接入 IDEA 的完整过程来写，把那些"配完了但还是跑不起来"的细节一次性说透。适合刚开始学 Spring Boot、或者公司新发了 Windows 电脑需要搭 Java 开发环境的同学直接照着操作。
1. Maven 下载与 "安装未完成" 的常见原因
很多人卡在第一步，下载完解压之后，命令行输入mvn -v提示不是内部或外部命令。这不是 Maven 坏了，是后面的环境变量和路径没有对齐。但在动环境变量之前，先确认 Maven 本体是正常的。
1.1 下载版本怎么选
去 Maven 官网下载二进制压缩包，选择apache-maven-3.9.9-bin.zip这种 bin 版本，不要下载源码版。另外，现在 Maven 4 已经发布了，但生态里大量插件和公司内部私服可能还没完全适配，稳妥起见，企业项目建议还是用 3.8.x 或者 3.9.x 版本。
Windows 上建议把压缩包解压到一个没有空格和中文的路径下。比如：
D:\dev\apache-maven-3.9.9尽量不要放在C:\Program Files\Apache\...这类路径里。虽然配完环境变量也能用，但后续一些脚本和工具扫描目录时，空格会导致各种奇奇怪怪的问题，没必要给自己埋雷。
1.2 检查 JDK 环境是前提
Maven 本身是 Java 写的，所以它依赖JAVA_HOME环境变量。如果你电脑上已经有 IDEA，并且能正常运行 Java 项目，那 JDK 基本是没问题的。
可以在命令行输入以下命令验证 JDK 是否就绪：
java -version如果提示找不到 java，那就要先去配置 JAVA_HOME。Maven 3.9 要求 JDK 8 以上，如果你用的是 JDK 17 或者 JDK 21，完全没问题。
一个常见的坑是：系统里装了多个 JDK 版本。比如 IDEA 自带了 JBR (JetBrains Runtime)，你又单独装了 Oracle JDK 和 OpenJDK，环境变量互相覆盖，或者 PATH 里前面的路径把后面的覆盖了。这种情况下，Maven 会莫名报错，有时还报UnsupportedClassVersionError。
建议在系统环境变量里把JAVA_HOME固定到你希望 Maven 使用的那个 JDK 路径，不要让它去猜。
1.3 确认 Maven 本身是否有问题
解压之后，直接进入 Maven 目录下的 bin 文件夹，在地址栏输入 cmd 并回车打开命令行，然后执行：
mvn -v如果这里能正常打印出 Maven 版本和 Java 版本，说明 Maven 安装包本身是好的，问题出在环境变量没配好。如果这里也报错，那就检查一下 java 是否可用，以及 Maven 解压包是否完整。
2. 环境变量配置的底层逻辑与常见误区
环境变量这部分，网上教程参差不齐。有些教程让配MAVEN_HOME，有些让直接配PATH，还有人让配CLASSPATH，新手很容易看懵。这里把原理讲清楚。
2.1 MAVEN_HOME 与 PATH 各管什么
MAVEN_HOME只是一个约定俗成的变量名，Maven 本身并不强依赖它。真正起作用的是 PATH 里的那一条记录。
但是实践当中，我依然建议保留MAVEN_HOME。因为很多 IDE 和开发工具在自动探测 Maven 时，会去读系统变量里有没有MAVEN_HOME，如果你填的是绝对路径也能识别，但维护起来不如变量方便。
具体操作步骤如下：
- 右键"此电脑" -> 属性 -> 高级系统设置 -> 环境变量。
- 在系统变量区域点击"新建"：
变量名：MAVEN_HOME 变量值：D:\dev\apache-maven-3.9.9- 在系统变量里找到
Path，点击编辑，新增一条：
%MAVEN_HOME%\bin- 确定保存，然后重新打开一个命令行窗口，输入
mvn -v验证。
这里想特别强调，改完环境变量之后，如果你用的是 Windows Terminal，不需要重启电脑，但必须新开一个标签页。因为已经打开的命令行窗口里缓存的还是旧的环境变量。
2.2 不要乱配 CLASSPATH
有些老教程会教你在环境变量里新建一个CLASSPATH，指向.或者%JAVA_HOME%\lib。这在远古时代可能有用，但现在完全没有必要，反而会干扰一些现代 Java 项目的运行。
我见过有同学照抄网上教程配置了 CLASSPATH 之后，Spring Boot 项目启动时类加载错乱，找了一下午问题，最后发现是这个环境变量在捣乱。所以记住：不配 CLASSPATH。
2.3 可选配置：MAVEN_OPTS
如果你的电脑内存比较充足，可以配置一下 Maven 的 JVM 参数，避免后续构建大项目时内存溢出。
新建系统变量：
变量名：MAVEN_OPTS 变量值：-Xms512m -Xmx1024m这个不是必须项，但如果你用 IDEA 构建大型微服务项目时频繁报OutOfMemoryError: Java heap space，可以考虑加上。
3. settings.xml 配置：仓库路径与阿里云镜像的实战调整
Maven 的核心配置文件是conf/settings.xml。这个文件里最值得关注两个点：一是本地仓库路径，二是中央仓库的下载源。
很多人在 IDEA 里折腾了一上午，项目还是爆红，最后发现是依赖下载不下来，根源就是没配镜像。国内环境访问 Maven Central 非常不稳定，所以阿里云镜像几乎是标配。
3.1 修改本地仓库路径
默认的本地仓库路径在用户目录下的.m2/repository。C 盘空间本来就不够用，随着项目增多，这个目录能膨胀到几个 GB，到时候清理起来太痛苦。
打开settings.xml，找到被注释掉的<localRepository>节点，改成你自己的路径：
<localRepository>D:\dev\maven-repository</localRepository>注意，这个路径后面不要带/，就是一个普通目录路径。Maven 第一次下载依赖时会自动创建这个目录。
3.2 配置阿里云镜像
在<mirrors>节点中加入下面的内容：
<mirror> <id>aliyunmaven</id> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror>这里解释一下，mirrorOf的值表示要镜像哪个仓库。写central表示只对 Maven Central 进行镜像替换。如果你的项目需要用到 JitPack 或者其他公共仓库，mirrorOf可以写*，但是通常不建议，因为可能会影响一些特殊仓库的拉取逻辑。
一个很实用的技巧是，在 Maven 中央仓库拉取某个依赖失败时，可以去阿里云的仓库搜索页直接搜了一下看看有没有这个 jar 包。很多冷门库阿里云也同步了，确认存在之后，问题基本就出在本地缓存或配置上了。
3.3 settings.xml 配置的群迁移方案
公司或者团队内部，可以维护一份公共的settings.xml，配置好仓库路径、镜像地址、JDK 编译级别，然后让大家直接覆盖本地文件。这样可以省去每个新成员都去踩一遍配置环境的坑。
不过要提醒一点，如果你用的是公司内部的 Maven 私服（比如 Nexus），那么 settings.xml 里要配置的应该是私服地址，而不是阿里云公共仓库。私服的配置涉及到<servers>节点，需要输入账号密码，这部分和公共配置是分开的。
4. IDEA 集成 Maven：替换内置 Maven 的完整步骤
IDEA 自带了一个捆绑的 Maven，但对很多实际项目来说，直接用内置的不太合适。因为内置版本可能与你期望的版本不一致，而且本地仓库和镜像配置你可能已经在 settings.xml 里调好了，IDEA 却还在用默认的.m2目录。
4.1 IDEA 中指定 Maven 主路径
打开 IDEA，进入 File -> Settings（或者直接按 Ctrl + Alt + S），搜索 Maven。
在 Maven home path 那里，选择你本机解压的 Maven 目录：
D:\dev\apache-maven-3.9.9User settings file 选择你修改过的settings.xml：
D:\dev\apache-maven-3.9.9\conf\settings.xmlLocal repository 会自动读取 settings.xml 里的配置，只要上一节你没配错，这里会显示成D:\dev\maven-repository。
这一步做完之后，IDEA 右下角会提示 Maven 配置已更新，可能需要重新导入项目。
4.2 Runner 里的 VM 选项
在 Maven 设置页面的 Runner 选项卡里，把 JRE 选择为项目使用的 JDK 版本，并且在 VM Options 里加上：
-Xmx1024m这样做的好处是，使用 IDEA 右侧 Maven 工具窗口点击打包或编译时，JVM 参数是可控的。如果没有这个配置，一些项目打包时会在maven-compiler-plugin阶段报内存不足。
4.3 创建新项目时的细节
新建一个 Spring Initializr 项目时，IDEA 默认会通过start.spring.io拉取项目骨架。这一步经常超时。
有两个解决途径：
- 在创建项目时，把 Server URL 改成阿里云的 Spring Initializr 镜像：
https://start.aliyun.com - 或者保持默认，如果超时，就改用一个干净的工程模板，然后手动在 pom.xml 里加依赖。
我个人的习惯是：不使用 Spring Initializr 网页生成，直接在 IDEA 里建一个空的 Maven 项目，然后把 pom.xml 里的骨架和相关依赖手写进去。这样虽然多花两分钟，但每一步都是可控的，网络问题影响最小。
4.4 导入旧项目时常见的依赖无法自动导入
IDEA 打开一个已有的 Maven 多模块项目时，有时候会出现 Maven 面板里项目是灰色的，或者依赖一直解析不了。
解决办法是点 Maven 面板顶部的刷新按钮，让 IDEA 重新读取 pom.xml 并下载依赖。如果刷新之后还是不行，先检查 IDEA 使用的 Maven 配置是不是正确，再看一下本地仓库的目录有没有报错日志。大多数情况下，都是 settings.xml 里的镜像路径配错了，导致依赖下载 401 或者 connect timeout。
5. 构建过程中会遇到的经典问题与解决思路
配置都弄好之后，最终要落实到能正常构建项目。这里整理几个我在实际使用中经常遇到的问题，不是网上到处都有的笼统描述，而是排查链路比较完整的实战案例。
5.1 依赖冲突：NoSuchMethodError 和 ClassNotFoundException
Maven 项目最经典的问题就是 jar 包冲突。比如你引入了 A 库和 B 库，A 库底层依赖了 C 库的 1.0 版本，B 库底层依赖了 C 库的 2.0 版本。Maven 默认会使用依赖树中"路径最短"的那个版本，但如果你没有明确排除，最终可能把两个版本的类都加载到 classpath 里。
排查工具很简单，在 IDEA 的 Maven 面板里，点击某个模块 -> Show Dependencies，能看到完整的依赖树。如果发现同一个 jar 出现了多次且版本不同，右键直接排除不需要的那个：
<exclusions> <exclusion> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> </exclusion> </exclusions>5.2 依赖下载速度慢或下载失败
这基本就是镜像没配好，或者本地仓库里缓存了错误的 .lastUpdated 文件。
一个很隐蔽的坑是：某个 jar 包在中央仓库已经更新了，但你本地.m2目录里缓存了一个损坏的_remote.repositories记录，导致每次 Maven 都以为本地已经下载过了，但实际 jar 文件是坏的，编译时就报找不到某个类。
解决办法很简单，找到本地仓库对应目录，把_remote.repositories和.lastUpdated后缀的文件删掉，然后重新执行mvn clean compile。我一般直接把整个仓库里所有.lastUpdated文件批量删除：
cd /d D:\dev\maven-repository for /r %i in (*.lastUpdated) do del "%i"这条命令在 Windows CMD 下可以直接运行。删完再刷新 IDEA 和 Maven，依赖就会强制重新下载了。
5.3 构建时编码 GBK 问题
Windows 环境下，Maven 构建时经常看到这样的警告：
[WARNING] File encoding has not been set, using platform encoding GBK这个问题在编译阶段可能不报错，但一旦项目里有中文字符串，或者使用了反序列化相关的功能，编码不一致就会出大问题。
解决方法是在项目根目录的pom.xml中显式设置编码：
<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties>同时，在 IDEA 的 Settings -> Editor -> File Encodings 里，把 Global Encoding、Project Encoding、Default encoding for properties files 全部设置为 UTF-8。
5.4 本地仓库疯狂占磁盘空间
用了一段时间后，本地仓库很容易超过 10GB。虽然这个问题不影响构建，但会让电脑存储吃紧。
清理方式有两个：
- 手动删除没有在用的旧版本目录，只保留项目实际依赖的版本。
- 使用 Maven 依赖插件分析，例如
dependency:analyze可以找出未被使用的依赖。
我个人的习惯是定期打开本地仓库，按日期排序，把半年以上不用的整个子目录删掉。下次需要的时候 Maven 会自动重新下载，不用担心删坏什么。
6. 在命令行中直接使用 Maven
IDEA 里能点按钮构建，但有些场景还是绕不开命令行直接操作，比如在 CI/CD 脚本里、或者单纯想执行mvn clean install -DskipTests。这是 Windows 上使用 Maven 的终极大法。
6.1 Windows Terminal 和 CMD 下的操作
打开 Windows Terminal（或者 CMD），直接输入：
mvn clean package -Dmaven.test.skip=true如果你想跳过 Test 阶段的编译，加-Dmaven.test.skip=true；如果只是想跳过测试执行但保留测试代码编译，用-DskipTests。这两个参数的区别在排查问题时很有用。
6.2 Maven 多模块项目命令行操作
对多模块项目，在根目录执行：
mvn clean install -pl module-a -am-pl指定要构建的模块，-am表示同时构建该模块依赖的其他模块。在 Windows 上这个命令要注意前面的参数顺序，不要写反，否则会报Could not find the selected project in the reactor。
6.3 配置全局 Maven 仓库镜像之后的加速效果
前面配置了阿里云镜像，下面实际感受一下差距。
我在一次构建中，没有配镜像，拉取一个大约 200 个依赖的项目，等了差不多 15 分钟还没结束。配好镜像之后，重新构建的时间降到了 1 分多钟。当然这个时间取决于具体网络环境，但国内开发环境配了镜像确实是有本质提升的。
7. 安装配置完成后的一些个人实操体会
最后聊几个我在日常使用中总结出来的经验，不一定写在官方文档里，但能少走不少弯路。
第一，Maven 版本不要频繁追新。Maven 3.9.x 是目前最稳的选择，很多 IDE 插件和 CI 工具都针对这个版本测试过。Maven 4 的有些插件兼容性还没有完全跟上，等生态稳定后再升级不迟。
第二，IDEA 里的 Maven 设置尽量和命令行下的 Maven 设置保持一致。也就是说，你在 IDEA 里指定了外部 Maven 和 settings.xml，那么在终端里配的 MAVEN_HOME 最好也是同一个版本。否则容易出现"IDEA 里构建没问题，命令行一跑就报错"的情况。两者不一致，后面排查问题时会增加不必要的复杂度。
第三，多模块项目里，尽量使用统一的父 pom 来管理依赖版本。这样在 Windows 上构建时，全项目只需要拉取一次依赖树，避免了子模块各自补全导致的版本混乱。
第四，上面这份配置流程，几乎所有步骤都是从零开始的，没有涉及任何付费工具的破解或异常激活流程。我用的一直是 IntelliJ IDEA Community Edition 或者公司提供的正版授权，Maven 本身就是 Apache 开源项目，完全不存在版权和授权问题。
按这个流程操作完，你应该能在 Windows 上顺畅地跑起 mvn 命令，并且让 IDEA 完全跟随你的 Maven 设置走。
接下来可以放心地创建一个 Spring Boot 项目，写一个 Controller，然后执行mvn spring-boot:run，看到项目正常启动，就说明整套环境已经完全打通了。
