刚开始用Maven时，我以为在Windows上装好就是下载、解压、配环境变量，然后敲几个命令完事。结果第一次在一台新电脑上配置，卡了快一上午。后来发现不是下载的包不对，而是JAVA_HOME被配成了JRE的路径，Maven死活起不来。这篇文章就把整个Windows下Maven安装和使用的过程完整整理一遍，从版本选择、环境变量、settings.xml，到第一个项目的完整构建流程，以及几个非常容易踩的坑，给同样准备入门的读者参考。

这种环境安装类的事情，网上教程很多，但大多是“照着敲能跑、换个环境就不行”。我希望这篇文章能让你明白每一步在做什么、为什么要这么做，这样遇到问题时不至于两眼一抹黑。

1. Windows下装Maven前，先把这几个底层问题想清楚

1.1 Maven不是“装个包”而已

很多初学者的第一反应是：Maven就是用来下载依赖的工具。这个理解没错，但不完整。Maven真正解决的是构建流程的标准化问题：项目用什么目录结构、编译用哪个JDK版本、测试怎么执行、最终打成JAR包还是WAR包，这些繁琐的事情通过一套约定就能统一处理。

把Maven装好，意味着你的项目从源代码变成可运行产物的完整生命周期有了可复现的脚本。团队里任何一个人拿到项目，执行同一套命令就能得到同样的结果。这也是为什么Java项目几乎都会配一个pom.xml。

1.2 版本匹配：JDK版本决定Maven版本上限

我见过不少人是随便下一个Maven版本，报错了才开始怀疑环境。这里有个很基础的匹配关系：Maven本身是用Java写的，运行Maven需要本机装有JDK，而且不同Maven版本对JDK版本的要求不同。

目前比较常用的Maven 3.6.x要求JDK 1.7以上，Maven 3.8.x和3.9.x要求JDK 8以上。如果你用的是Maven 3.9系列，JDK 8、11、17、21一般都没问题，但如果你本机只装了JDK 1.6或更老，那就只能找老版本的Maven，这不现实，建议直接升级JDK。

具体选哪个版本，我会建议选最新的Maven 3.9.x稳定版。原因有两个：一是和现代JDK的兼容性更好，二是3.x系列在Windows下的使用经验最丰富，遇到问题容易搜到解决方案。别去尝鲜Maven 4.x，除非你想当小白鼠。

1.3 确认JAVA_HOME指向JDK而不是JRE

这是Windows下最常见、也最隐蔽的一个坑。很多Windows系统的机器在安装JDK后，其实还带着一个单独的JRE。如果你在环境变量里把JAVA_HOME配到了JRE目录，Maven启动时会直接提示找不到编译器环境，或者干脆报出奇怪错误。

检查方法很简单：在命令行执行

echo %JAVA_HOME%

正常情况下应该指向类似C:\Program Files\Java\jdk-17这样的路径，而不是C:\Program Files\Java\jre17。可以用下面这张表快速核对：

如果javac命令提示找不到，说明Path里没有JDK的bin目录，这在后面配置环境变量时会一并解决。

2. 下载解压与目录结构：装到C盘外，后面会省很多事

2.1 下载时别选错包：bin.zip与src.zip

去Maven官网的下载页面，会看到一连串文件。需要选择的是apache-maven-3.9.x-bin.zip，这才是可直接运行的二进制发行包。旁边那些-src.zip是源码包，下载下来没法直接运行。Windows用户不要点tar.gz，那是给Linux和macOS准备的，Windows下解压不是不行，但没必要。

下载完成后得到一个zip压缩包，解压即可，不需要安装程序。Maven本身是绿色软件，这点和Linux上的使用习惯很像。

2.2 解压后目录结构速览

解压后你会看到一个以版本号命名的文件夹，比如apache-maven-3.9.6。打开里面是这样的：

apache-maven-3.9.6/ ├── bin/ # mvn可执行脚本 ├── conf/ # 核心配置文件settings.xml ├── lib/ # Maven运行所需的jar包 └── boot/ # Maven自身启动的类加载器

初学者最容易忽略的是conf/settings.xml和bin/mvn.cmd。前者是全局配置文件，本地仓库位置、镜像源、代理信息都在这里改；后者是Windows下的启动脚本，环境变量验证时看的就是它。

2.3 目录路径的两个忌讳

解压位置看起来无所谓，但实际在Windows下有两个忌讳：

第一，路径不要带中文和空格。比如D:\软件\maven这种路径，在某些旧版工具链里会出现编码或路径解析问题。建议放在D:\tools\apache-maven-3.9.6这样的纯英文路径下。

第二，尽量不要装到C盘系统盘。Maven的本地仓库默认是在用户目录下的.m2文件夹，一旦项目多了，依赖包体积会迅速膨胀。C盘空间紧张会拖累系统。如果你把Maven本身也放在C盘，后面想挪会很麻烦。

3. 环境变量设置与验证：这一步翻车概率最高

3.1 从新建MAVEN_HOME到修改Path

解压完并不代表装好了，还差最关键的一步：环境变量。Windows下配置Maven环境变量需要两个动作。

右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量，在“系统变量”区域点击“新建”，变量名填MAVEN_HOME，变量值填Maven的解压路径。比如：

MAVEN_HOME = D:\tools\apache-maven-3.9.6

然后在已有的Path变量里追加一条：

%MAVEN_HOME%\bin

为什么要专门建一个MAVEN_HOME再引用，而不是直接写完整路径？一是之后升级Maven版本时只需要改MAVEN_HOME这一个地方；二是很多工程化工具会自动读取MAVEN_HOME环境变量，提前配好能省不少事。

3.2 命令行验证：mvn -v 输出应该长什么样

配置完成后，重新打开一个命令行窗口（注意，旧窗口可能不会刷新环境变量），执行：

mvn -v

正常情况下会输出一段信息。重点看两行：

Apache Maven 3.9.6 (... Maven home: D:\tools\apache-maven-3.9.6 Java version: 17.0.10, vendor: ... Java home: C:\Program Files\Java\jdk-17

Maven home对，Java home对，说明环境变量配置成功。如果输出的是“不是内部或外部命令”，大概率是Path没配置好，或者命令行窗口没重开。

3.3 验证失败的常见原因排查

我在实际中遇到过一种很隐蔽的情况：机器上装了多个JDK，Path里既有JDK 8的路径，又有JDK 17的路径，导致Maven启动时用了错误版本。解决办法是在Path里把希望使用的JDK bin目录排到前面，或者干脆把多余的JDK环境变量清理干净。

4. settings.xml才是安装的重头戏：本地仓库和镜像配置

4.1 先搞清楚settings.xml什么时候生效

装好Maven后，大多数人直接就打开项目开始下载依赖。这时候如果发现下载特别慢，或者依赖很难拉全，问题基本都出在Maven的配置文件上。

Maven有两个层级的settings.xml：全局配置文件在%MAVEN_HOME%\conf\settings.xml，用户级配置文件在C:\Users\<用户名>\.m2\settings.xml。如果两个都存在，用户级的会覆盖全局配置。实际使用中，我更建议直接改全局配置文件，因为用户级的文件不会自动创建，很多初学者根本不知道它的存在。

4.2 修改localRepository：把依赖仓库挪出C盘

打开conf目录下的settings.xml，找到下面这段默认注释内容：

<localRepository>${user.home}/.m2/repository</localRepository>

默认情况下，所有下载下来的依赖jar包都会存到用户目录的.m2/repository文件夹里。这有两个问题：一是C盘空间压力大，二是一旦系统重装，这些依赖全没。

我的做法是把它改成D盘的一个固定目录：

<localRepository>D:\maven-repo</localRepository>

改完后，本地仓库就统一放到D盘。以后重装系统、换Maven版本，只要路径不变，依赖包还能继续使用，省去重新下载的麻烦。注意，改完这个路径后，第一次执行Maven命令会自动创建该目录，不需要手动创建。

4.3 镜像源配置：解决国内下载慢的问题

Maven默认从中央仓库下载依赖，这个仓库服务器在国外，国内访问经常很慢或者直接卡住。解决思路很直接：配置一个国内公共仓库镜像。

在settings.xml的<mirrors>标签内，添加一个mirror节点。这里以国内常用的公共仓库地址为例：

<mirror> <id>public-mirror</id> <mirrorOf>central</mirrorOf> <name>Public Mirror</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

这里的关键是<mirrorOf>central</mirrorOf>，表示所有对中央仓库的请求都走这个镜像。实际使用中，这个地址的下载速度和稳定性比默认仓库可靠得多。类似的公共镜像还有几个，比如腾讯云、华为云的Maven仓库，配置方式完全一样，只需要换一下url。如果某个镜像不稳定，换一个就行。

4.4 镜像配置的两个小细节

不少人在这一步栽过跟头。配置镜像后，下载速度确实快了，但有些项目里有特殊依赖来自某个私有仓库。如果mirrorOf写的是*，那所有仓库的请求都会被镜像劫持，私有仓库里的依赖反而拉不下来了。

我的习惯是镜像只覆盖中央仓库，即mirrorOf写成central。如果项目里确实需要额外仓库，再单独在pom.xml里配置仓库地址，这样各司其职。另一个细节是，修改settings.xml后需要重启IDE才会生效，否则IDE里用的还是旧配置。

5. 跑通第一个构建：核心命令与一个能用的pom.xml

5.1 最小pom.xml长这样

环境配好、镜像配好之后，该实际跑一个项目了。不管你现在用的IDE是什么，第一步都可以先建一个纯命令行的Maven项目来验证整条链路。

在任意目录下新建一个pom.xml文件，内容可以非常精简：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>demo-maven</artifactId> <version>1.0-SNAPSHOT</version> <packaging>jar</packaging> <properties> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> </project>

groupId、artifactId、version这三个坐标共同决定了一个Maven项目的身份。source和target两个属性分别表示源码的Java版本和编译后class文件的版本，如果你的JDK是11就写11，是8就写8，别直接照抄17。

5.2 从clean到install，完整命令顺序

在pom.xml所在目录打开命令行，按顺序执行下面几条命令：

mvn clean compile mvn test mvn package mvn install

这里简单说明每一条的作用。

mvn clean是清理target目录，把之前的编译产物删掉，避免残留文件影响新的构建。

mvn compile编译主代码到target/classes。

mvn test执行src/test/java下的单元测试。

mvn package把项目按照pom.xml中packaging指定的方式打包成jar或war，文件生成在target目录下。

mvn install会把打包产物安装到本地仓库。这部分很多初学者不理解：为什么要install？因为同一个机器上有多个项目互相依赖时，A项目想用B项目的jar包，B项目必须先install到本地仓库，A项目才能以依赖方式引用。

5.3 三个特别容易混的命令

实际开发中，clean经常和后面命令连用，最常见的是mvn clean install。我看到很多人只执行package，然后在别的项目里引用时发现找不到依赖，就是没搞清楚install和package的区别。

5.4 IDE里配置Maven：用自己装的，别用自带的

如果你用的是常见Java IDE，比如IDEA，打开项目后IDE默认会使用它自带的Maven。这个自带版本通常没问题，但会有两个隐患：一是自带Maven的settings.xml可能不是你自己配置的镜像，下载依然慢；二是升级IDE后Maven行为可能变化。

建议手动把IDE里的Maven指向自己安装的版本。以IDEA为例，进入 Settings -> Build, Execution, Deployment -> Build Tools -> Maven，依次设置：

• Maven home path：选到你的Maven解压目录
• User settings file：勾选Override并选择你的settings.xml路径
• Local repository：如果配置的是D:\maven-repo，这里会自动读取

设置完重启项目，让IDE重新导入Maven配置。第一次导入会下载很多依赖，只要镜像配好了，速度一般很快。

6. 实战中遇到的高频问题与排查链路

6.1 中文乱码：从环境变量到IDE的一整套解法

Maven构建日志里如果中文变成一堆问号或乱码，通常不是代码问题，而是默认编码不一致。先检查pom.xml里是否设置了：

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

如果设置了还是乱码，再看命令行窗口的代码页。在Windows的cmd里执行：

chcp 65001

切换到UTF-8编码。如果是IDE的控制台，在IDE的启动参数里加一行-Dfile.encoding=UTF-8，然后重启IDE。通常这一套操作下来，乱码问题基本能解决。

6.2 依赖下载失败或卡住：.lastUpdated文件是什么

镜像配好了，但偶尔还是会遇到某个依赖下载失败，之后再执行命令就一直卡在同一个jar包。此时本地仓库对应目录下会出现.lastUpdated后缀的文件，这是Maven记录下载失败状态的标记文件。

只要这个文件存在，Maven就不会重新尝试下载。清除方式很简单：在命令行执行

mvn -U clean compile

其中-U参数强制检查远程仓库更新。更彻底的做法是手动删除本地仓库中对应目录下的lastUpdated文件，再重新构建。我在项目里遇到过这种场景：明明换了镜像源，某个快照版本依赖还是反复失败，后来发现是本地仓库里的失败记录没清理。

6.3 依赖冲突：用dependency:tree看依赖树

项目稍微变大，就可能出现两个依赖传递引入了同一个库的不同版本。现象很典型：编译正常，运行时报NoSuchMethodError或ClassNotFoundException。

排查思路很简单，执行：

mvn dependency:tree

Maven会把整个依赖树打印出来，你很快能看到同一个groupId出现了多个版本。处理方式是在pom.xml中显式声明需要用到的版本，或者对某个传递依赖做排除。

<dependency> <groupId>org.example</groupId> <artifactId>demo-lib</artifactId> <version>1.0.0</version> <exclusions> <exclusion> <groupId>org.example</groupId> <artifactId>conflict-lib</artifactId> </exclusion> </exclusions> </dependency>

6.4 新电脑装Maven的个人习惯

最后分享一点我自己的习惯。每次在一台新Windows电脑上装Maven，我不会先急着执行IDE里的项目，而是先按下面这个顺序走一遍：

第一，用java -version和javac -version确认JDK可用，再执行mvn -v看Maven是否识别到正确的Java环境。第二，把settings.xml里的本地仓库路径和镜像源先改好，然后执行一个最简单的mvn help:system命令，让Maven自动初始化本地仓库并读取配置。第三，跑一个最简单的pom.xml项目，把clean、compile、package整条链路走通，再打开IDE导入项目。

这套流程每次都能帮我提前发现环境问题，而不是等IDE里项目导入失败后才开始排查。如果你是第一次在Windows下配置Maven，建议也按这个顺序来，能少走很多弯路。