1. 准备工作：JDK版本没选对，后面全白搭
先说个我印象比较深的场景。前阵子有个同事在群里发截图，说自己Maven装好了、环境变量也加了，mvn -v一转圈就报JAVA_HOME is not defined correctly。我远程一看，JDK装的是21，Maven用的是那种极老版本，俩货互不认账。所以这篇教程第一步不是急着下载Maven，而是把JDK的事情捋清楚，免得后面所有操作都在给前面埋雷。
1.1 为什么Maven非要依赖JDK
Maven这工具本身是用Java写的，它拿到你的构建指令之后，要在一大堆Java类库的支撑下解析pom.xml、算依赖树、编译源码。没有JDK，它就等于一个没有引擎的车，方向盘动得再欢也迈不出半步。注意，光装JRE（Java运行环境）是不够的，因为Maven执行compile的时候需要调用javac来编译.java文件，javac在JRE里根本没有。所以必须装完整版JDK。
如果你想确认自己机器上有没有装过JDK，打开命令提示符（Win+R后输入cmd回车），敲一行：
java -version如果有输出，说明装了JRE或JDK；再敲一行：
javac -version如果第二行报“不是内部或外部命令”，那不好意思，你这个环境大概率只有JRE或者没装JDK，Maven是跑不起来的。此时不要犹豫，直接补装JDK。
1.2 JDK版本选择：不是越新越好，要看你手头的项目
热门搜索词里经常有人问“maven是干嘛的”“idea安装教程”，说明不少人是刚进Java坑的新手。新手选JDK版本，我只有一个建议：别盲目上最新版，先看你的项目和身边同事用的版本。
大致规律是这样的：
- 老项目、公司自研框架、接的外包项目：普遍还在Java 8（JDK 1.8），这个版本生态最稳，Maven 3.6.x配合JDK 8几乎是黄金组合。
- 新项目、微服务架构、Spring Boot 2.x/3.x：多数已经升级到JDK 11或17。
- 追求新特性的个人项目和2024年之后新起的Spring Boot 3.x项目：JDK 17是主流，21也开始普及。
我一般推荐新手直接装JDK 17出不了大错。它比JDK 8更能应付新框架，又比JDK 21遇到的未知坑少得多。不过如果你明确知道自己要维护Java 8的老项目，那就老实装8，Maven版本再配合挑3.6.3一类的。
还有个小细节：Maven每个大版本对JDK有最低要求，Maven 3.8.x可以跑在JDK 8及以上，Maven 3.9.x官方也支持JDK 8以上的环境。反过来说，如果你装了Maven 3.9.x又用JDK 8，也能跑，只是一些新插件可能对旧JDK不友好。保险的策略是：JDK 8 + Maven 3.6.x打包使用，JDK 17 + Maven 3.9.x打包使用。
1.3 JDK安装时的两个隐藏雷点
第一，安装路径不要带空格和中文。很多人图省事装在C:\Program Files\Java\jdk-17，你后面配JAVA_HOME时还要处理路径带上空格带来的引号问题，何苦折腾。建议直接装在D:\Java\jdk-17这类目录，又干净又好记。
第二，安装时强烈建议把“公共JRE”也勾装上，虽然不少教程说不需要，但后面你要是跑一些老脚本或者用第三方工具，会省很多事儿。安装完成后，手动把JAVA_HOME配置好再进入下文，配置方法和后面Maven完全一样，就是加一个系统变量指向JDK的解压目录。这里先不展开，因为Maven的配置你会完完整整操作一遍，到时候顺手就把JAVA_HOME一起写了。
2. Maven下载与解压：认准官方包，避开坑爹版本
2.1 从哪下载最靠谱
正如热搜词里赫然写着“maven官网”“maven官网下载入口”，说明很多人第一个问题就是找不到靠谱的下载地址。我用过的下载方式有三种，按推荐程度排序：
第一，直接访问Apache Maven官网，找到Download那一栏，往下滑能看到一个表格，里面是各个历史版本对应的二进制包。我只推荐下载apache-maven-3.9.x-bin.zip或apache-maven-3.6.x-bin.zip这种后缀带bin的压缩包，不要下src结尾的源码包，那个是给开发者看源码用的，不能直接当工具用。
第二，国内镜像站下载。如果你所在网络访问Apache官网特别慢（这在某些网络环境下经常发生），可以去清华大学开源软件镜像站或阿里云镜像站找Maven的目录，下载速度非常可观，而且版本同步也比较及时。
第三，IDEA自带的Maven插件（指的是IDEA内置的Bundled Maven）只是应急用，不建议作为主力。后面讲IDEA集成时你会明白为什么。
2.2 下载后放哪，怎么解压
拿到zip压缩包后，解压到哪也是很多人没想清楚的问题。个人强烈建议解压到一个全英文、无空格的固定位置，比如：
D:\develop\maven\apache-maven-3.9.6不要在桌面上解压，也不要在系统盘藏得太深。因为后面配置MAVEN_HOME、配置settings.xml、IDEA里指向Maven主目录，一大堆地方都要写这个路径，路径越短越不容易写错。
解压完，打开这个目录，正常情况下应该能看到bin、boot、conf、lib等文件夹。如果你发现解压出来只有一堆.jar和奇怪的目录结构，大概率是下错了包。
2.3 关于版本，我的真实建议
经常有新手一上来就下载最新版，图个心里踏实。但Maven这个工具，求新不如求稳。我自己在3.6.3和3.9.6之间反复横跳了很久，3.6.x胜在成熟稳定，配合JDK 8的项目特别稳妥；3.9.x对JDK 17以上的支持更好，插件解析速度和依赖解析逻辑也有优化。如果你没有历史包袱，直接3.9.x。如果你是在维护公司老项目，那就先看看项目根目录下面有没有mvnw（Maven Wrapper）文件，有的话它已经锁定了Maven版本，你就照那个来，不用自己操心。
3. 环境变量配置：三步设完，命令行里见真章
3.1 JAVA_HOME和MAVEN_HOME的完整配置操作
这是我帮人排查次数最多的环节，也是“明明全按教程弄了还是不行”的重灾区。配置环境变量一共三步，操作系统版本只要不是远古的Windows 7，操作都差不多。
打开方式：桌面“此电脑”上右键 → 属性 → 左侧“高级系统设置” → 右下角“环境变量”。在打开的窗口里，上半部分是用户变量，下半部分是系统变量。这里建议直接在系统变量里操作，这是网上大部分教程的做法，效果也最彻底。
点击下方的“新建”，依次把下面这几个变量加进去：
| 变量名 | 变量值（示例） |
|---|---|
JAVA_HOME | D:\Java\jdk-17 |
MAVEN_HOME | D:\develop\maven\apache-maven-3.9.6 |
还有一个变量是后面IDEA集成时经常要取用的，叫M2_HOME，老版本教程里爱用，新版本有些工具已经不读了。我的建议是顺手也加上，指到和MAVEN_HOME同一个路径，这样最保险：
|M2_HOME|D:\develop\maven\apache-maven-3.9.6|
然后回到环境变量列表里找到Path这一项，双击它（Windows 10以上是弹出一个列表形式的窗口），点右侧“新建”，追加三行：
%JAVA_HOME%\bin %MAVEN_HOME%\bin记得是追加，不是把原来的Path整个替换掉。很多人添加Path时不小心把原有变量值覆盖了，结果系统一堆命令都失灵了，这种事我见过不止一次。
3.2 验证是否配置成功
配置完成后，一定不能省掉验证步骤。关掉当前已打开的所有cmd窗口，重新开一个新的命令提示符窗口，依次执行：
java -version javac -version mvn -v前面两个如果有输出，第三个也能看到类似下面这样的内容，说明配置成功：
Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3fcfd13d9c3c5c8c) Maven home: D:\develop\maven\apache-maven-3.9.6 Java version: 17.0.9, vendor: Oracle Corporation, runtime: D:\Java\jdk-17 Default locale: zh_CN, platform encoding: UTF-8注意看输出里的Maven home是不是你刚配置的路径，Java version是不是你预期的版本。如果mvn -v提示“不是内部或外部命令”，排查顺序是：重新打开cmd了吗（这个最傻但最常发生）→MAVEN_HOME路径写对了吗 → Path里追加了吗 → 路径里有没有空格或中文。按这个顺序检查，百分之九十五的问题能解决。
3.3 验证失败时的快速定位清单
有一次帮人远程排查，对方信誓旦旦说配置跟教程一模一样，但mvn -v死活不认。我让他执行echo %MAVEN_HOME%，结果输出一个空行，这才发现他把变量名敲成了MAVEN_HOM，少了个E。这种低级错误在真实现场发生率惊人。再分享一个实用命令：
where mvn如果配置成功，这条命令会显示Maven的完整路径；如果显示找不到，那说明Path没生效。另外，如果你电脑上装了多个版本的Java或者Maven，where java和where mvn也能帮你看清当前到底用的是哪一个，避免新装的被旧版本顶掉。
4. settings.xml的灵魂配置：本地仓库、镜像和私服
4.1 仓库是什么，为什么必须配置
很多人配完环境变量就急着去IDEA里建项目，结果项目一创建，右下角就开始疯狂下载，一等就是半小时。原因很简单：Maven需要把你项目里用到的依赖从中央仓库拉到本地，这个过程国内网络经常慢到让人崩溃。
Maven的依赖管理有个核心逻辑：本地仓库优先，中央仓库兜底。所谓本地仓库，就是Maven在你电脑上专门存放依赖包的一个文件夹。每次构建项目时，Maven先看本地仓库有没有这个jar，有就直接用，没有再想办法上网下载。所以不管项目大小，本地仓库都是绕不开的一个重要角色。
默认情况下，本地仓库在C:\Users\你的用户名\.m2\repository，就藏在用户目录下。但这有个问题，很多人C盘空间本来就不宽裕，而一个大型项目的依赖动辄几个GB，全堆在C盘后期必然拖垮系统。所以我习惯让所有新手第一时间修改默认仓库路径，把它指到一个剩余空间充足的盘符下。
4.2 修改本地仓库路径
Maven的配置文件在安装目录下的conf\settings.xml，这是全局配置，影响这台机器上所有Maven项目。打开这个XML文件，找到注释掉的一行，长这样：
<!-- <localRepository>/path/to/local/repo</localRepository> -->把这行的注释解开，替换成你自己的路径：
<localRepository>D:\develop\maven-repository</localRepository>注意XML文件里的路径分隔符要用正斜杠/。改完保存，以后所有依赖包都会下到这个文件夹里，C盘压力骤减。
4.3 配置阿里云镜像，下载速度立竿见影
这一步是整个配置里体验提升最明显的一环，同时也是最容易被人忽略的。热搜词里“下载maven”“maven依赖管理”频繁出现，恰恰说明很多人都卡在下载环节。Maven默认的中央仓库在国外服务器，国内网络拉取依赖包经常速度慢如蜗牛，或者下载到一半直接报连接超时。解决办法就是换成国内镜像。
在settings.xml里的<mirrors>标签下，添加一个阿里云的镜像配置：
<mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>mirrorOf填central表示只对中央仓库做镜像镜像，不影响你自己配置的其他私服仓库，这个写法比粗暴的*更合理。阿里云这个公共仓库，相当于把Maven中央仓库存了一份在国内，你下载依赖走的就是国内路径，速度几乎可以直接拉满。我个人用过很多年，稳定性和同步速度都让人放心。
如果你是在公司环境工作，而且内部有Nexus私服，那就不要配阿里云了，改成公司私服地址，逻辑一样，只是<url>换掉。这个通常由公司的架构师或团队Leader统一发给你。
4.4 顺手把JDK编译级别锁定一下
settings.xml里的另一个常用配置项是<profiles>标签下指定JDK版本。不配的话，Maven在很多老项目上会默认用JDK 1.5的编译级别，导致明明用着JDK 17却疯狂报“无效的源发行版”。在settings.xml的<profiles>里加上：
<profile> <id>jdk-17</id> <activation> <activeByDefault>true</activeByDefault> <jdk>17</jdk> </activation> <properties> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> </profile>如果你用的是JDK 8，就把17全部改成1.8。项目源码编码统一设成UTF-8，能避免控制台中文乱码这个经典问题。
5. IDEA集成Maven：第一次创建项目最容易翻车的地方
5.1 别用IDEA内置的Bundled Maven
IDEA是自带Maven的，很多教程里也直接让你用内置的，图省事。但我的经验是，IDEA内置的Maven版本通常比较旧，而且它不一定跟我们刚才配置的settings.xml联动。你如果用了Bundled Maven，最后极有可能出现这种诡异局面：命令行里mvn clean package构建一切正常，IDEA里一刷新却报依赖找不到。
解决办法很简单，在IDEA里手动指定我们自己安装的Maven。打开IDEA，进入File -> Settings（Windows快捷键Ctrl+Alt+S），左侧菜单搜索框输入Maven，打开Build, Execution, Deployment -> Build Tools -> Maven。页面里有三个关键设置：
Maven home path：选成D:\develop\maven\apache-maven-3.9.6User settings file：勾选Override，然后选到D:\develop\maven\apache-maven-3.9.6\conf\settings.xmlLocal repository：勾选Override，填D:\develop\maven-repository
这三个选完后，点右下角Apply再点OK。这一步的作用就是让IDEA完全复用我们用命令行配置好的环境，两边行为一致，省得以后IDEA一套逻辑、命令行一套逻辑，互相打架。
5.2 创建Maven项目时容易踩的坑
新建项目时，New Project弹窗里左侧选Maven，这里有个很容易踩的坑：很多人随手选了Generate from archetype里的maven-archetype-quickstart模板，但如果你的网络不是特别顺畅，这个模板拉取过程经常失败。更稳妥的方式是：不勾任何archetype，直接创建一个最普通的Maven项目，让IDEA生成一个干净的pom.xml，然后自己维护依赖坐标。效果完全一样，但少了模板下载失败这一层打击。
项目创建完成后，耐心等右下角进度条跑完，让IDEA完成初始索引。首次导入阶段，它会读取你pom.xml里声明的所有依赖并下载到本地仓库，这个过程中最好别急着写代码，等Maven窗口提示空闲了再动手。
如果你连创建项目这一步都还没稳定的把IDEA装好，那就先放下Maven，去把IDEA环境解决，再回来用。热搜词里“idea安装教程”长期存在，说明这一步卡住了不少人。
5.3 把远程仓库地址、编译级别再在IDEA里核对一遍
IDEA的Maven设置里还有两个容易忽略的地方。第一，Runner->VM Options加上一行：
-Dfile.encoding=UTF-8不加的话，项目运行或测试时控制台的日志很容易出现乱码。第二，Importing选项里把JDK版本设置成跟pom.xml一致，尤其是当你的机器上装了好几个JDK时，IDEA可能会挑错。
还有一个细节要提醒：很多人改了settings.xml之后发现IDEA里没生效，是因为IDEA缓存了旧配置。此时点一下Maven面板里的刷新按钮（就是那个循环箭头的图标），它会重新读取配置。如果还是没反应，File -> Invalidate Caches...清一下缓存重启，基本上就正常了。
6. 对照组：项目pom.xml里需要理解的几个核心概念
6.1 groupId、artifactId、version到底在说什么
IDEA创建Maven项目时，会有一行让你填三个东西：groupId、artifactId、version。新手常常一脸懵，随手乱填，后面项目组件多了再回头改，麻烦得一塌糊涂。
简单类比一下：把每个依赖想象成一个快递包裹。groupId是发件方的组织名，比如公司域名反写com.example；artifactId是包裹里那个商品的具体型号，比如hello-service；version是第几代产品，比如1.0.0。三个组合在一起，就是Maven在仓库里找这个包裹的完整地址。
后面你给自己写模块时，这个就是唯一坐标，不要轻易改动。如果改了，依赖它的其他模块也要跟着改，一处漏改就是一堆报错。
6.2 常见依赖的引入姿势和排查方法
比如一个Spring Boot项目，pom.xml里通常会先继承父工程：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.0</version> <relativePath/> </parent>然后引入Web支持：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>这里注意，因为已经继承父工程了，version可以省略，由父工程统一管理。如果你把父工程去掉，所有依赖的version都得自己写，漏一个就会报missing artifact。
调试依赖问题最好的办法就是看IDEA右侧的Maven工具窗口，展开Dependencies节点，那里能看到每个依赖的真实版本和被什么依赖传递拉进来的。如果把鼠标悬停在某个依赖上查看详情，还能分析冲突，非常直观。
6.3 Maven生命周期和常用命令，配合IDEA使用
很多人搞不清clean、compile、package、install这些命令到底是什么关系。其实Maven有一套标准的生命周期，可以理解成做菜流程：clean是把脏盘子收拾掉，compile是切菜配菜，test是试吃，package是把菜装盘，install是把菜放进家里冰箱供其他菜谱取用。
IDEA里的Maven工具窗口，双击对应命令就能执行。日常开发最常用的组合是clean+install，这个组合会把项目编译、测试、打包并安装到本地仓库，这样同台机器上其他项目就能引用到最新版本。每当你改了一个公共模块的代码，记住先对它执行install，否则下游模块引用到的还是旧版本，这个坑我见过无数新人掉进去过。
7. 实测中的意外情况和故障排查手册
7.1 明明离线的依赖，IDEA却一直报找不到
这是我帮人排查时遇到频率最高的问题之一：项目里面之前编译得好好的，突然某天打开，IDEA噼里啪啦报红，一堆cannot resolve symbol。大部分情况下，问题源自本地仓库里的一些临时文件损坏，Maven下载依赖时如果网络中断，会在仓库里留下*.lastUpdated后缀的标记文件。解决方法是，打开本地仓库目录，搜所有的*.lastUpdated文件，全部删除，然后回到IDEA刷新Maven项目，让依赖重新下载。Windows下想要快速清理，可以在仓库目录下开一个终端执行：
del /S /Q *.lastUpdated删完再刷新，一般就好了。
7.2 项目可以编译，但IDEA识别不了Spring相关注解
这个经常是IDEA的Spring插件索引出了问题，跟Maven配置关系不大。处理办法是File -> Invalidate Caches，勾选Clear file system cache and Local History，重启IDEA让索引重新建立。顺便说一句，如果你发现自己用的IDEA是社区版（Community），而项目用到了Spring Boot，那你会遇到一个非常现实的问题——社区版默认不带Spring相关插件，很多Bean相关提示都不会出现。要么接受现实手动管理，要么换用旗舰版（Ultimate）。
7.3 修改了settings.xml但Maven就是不认
有一个几乎每个新人都踩过的坑：settings.xml改完，IDEA里也点了刷新，但下载速度还是乌龟爬。这时候十有八九是IDEA的User settings file没有点Override，IDEA仍在用自己默认位置下的settings.xml。另外，settings.xml文件一旦用带BOM的编码保存，XML解析器会把它当成一个不可见字符，Maven就会报处理错误或忽略部分配置。一定要用UTF-8无BOM编码保存，推荐用IDEA自己的编辑器改settings.xml，天然规避这个问题。
7.4 多JDK环境下的版本错乱问题
如果你电脑上装了多个JDK，比如为了维护老项目装了8，又为了新项目装了17，Maven可能会在构建时报奇怪的编译错误。此时最好确认一下项目pom.xml里的java.version属性，并配合Maven的Toolchains机制或IDEA里指定的JRE设置来控制。日常开发我建议只保留一个主力JDK，老项目实在要用，再考虑用IDEA里的Project Structure单独指定该项目的SDK。这样比全局环境变量来回改省心得多。
8. 最后再分享一个小技巧
整套流程走完之后，你其实还可以再进一步：给IDEA安装一个Maven辅助插件，比如Maven Helper，它能提供依赖冲突分析的一键按钮，快速高亮重复依赖和版本冲突。做微服务项目时，依赖树往往又深又乱，这个工具能帮你少掉很多头发。
另外，建议平时把~/.m2/repository或者你自定义的本地仓库路径加入杀毒软件白名单。Windows Defender在后台扫描大量小型jar文件时，会明显拖慢构建速度。加了白名单之后，我本地一个中型项目的构建时间从两分多钟直接降到了五十秒内，效果立竿见影。
最后关于学习路径多说一句：装好Maven、配好环境、跑通一个最简单的项目，这只是入门。真正熟练的标志是，你在不借助任何搜索引擎的情况下，能独立给一个模块写pom.xml、解决依赖冲突、掌握生命周期指令的灵活组合。到那时候，你回头看今天折腾的这些东西，会发现一切都值得。
