1. 准备工作JDK版本没选对后面全白搭先说个我印象比较深的场景。前阵子有个同事在群里发截图说自己Maven装好了、环境变量也加了mvn -v一转圈就报JAVA_HOME is not defined correctly。我远程一看JDK装的是21Maven用的是那种极老版本俩货互不认账。所以这篇教程第一步不是急着下载Maven而是把JDK的事情捋清楚免得后面所有操作都在给前面埋雷。1.1 为什么Maven非要依赖JDKMaven这工具本身是用Java写的它拿到你的构建指令之后要在一大堆Java类库的支撑下解析pom.xml、算依赖树、编译源码。没有JDK它就等于一个没有引擎的车方向盘动得再欢也迈不出半步。注意光装JREJava运行环境是不够的因为Maven执行compile的时候需要调用javac来编译.java文件javac在JRE里根本没有。所以必须装完整版JDK。如果你想确认自己机器上有没有装过JDK打开命令提示符WinR后输入cmd回车敲一行java -version如果有输出说明装了JRE或JDK再敲一行javac -version如果第二行报“不是内部或外部命令”那不好意思你这个环境大概率只有JRE或者没装JDKMaven是跑不起来的。此时不要犹豫直接补装JDK。1.2 JDK版本选择不是越新越好要看你手头的项目热门搜索词里经常有人问“maven是干嘛的”“idea安装教程”说明不少人是刚进Java坑的新手。新手选JDK版本我只有一个建议别盲目上最新版先看你的项目和身边同事用的版本。大致规律是这样的老项目、公司自研框架、接的外包项目普遍还在Java 8JDK 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的老项目那就老实装8Maven版本再配合挑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。如果你是在维护公司老项目那就先看看项目根目录下面有没有mvnwMaven Wrapper文件有的话它已经锁定了Maven版本你就照那个来不用自己操心。3. 环境变量配置三步设完命令行里见真章3.1 JAVA_HOME和MAVEN_HOME的完整配置操作这是我帮人排查次数最多的环节也是“明明全按教程弄了还是不行”的重灾区。配置环境变量一共三步操作系统版本只要不是远古的Windows 7操作都差不多。打开方式桌面“此电脑”上右键 → 属性 → 左侧“高级系统设置” → 右下角“环境变量”。在打开的窗口里上半部分是用户变量下半部分是系统变量。这里建议直接在系统变量里操作这是网上大部分教程的做法效果也最彻底。点击下方的“新建”依次把下面这几个变量加进去变量名变量值示例JAVA_HOMED:\Java\jdk-17MAVEN_HOMED:\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或者Mavenwhere 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 --把这行的注释解开替换成你自己的路径localRepositoryD:\develop\maven-repository/localRepository注意XML文件里的路径分隔符要用正斜杠/。改完保存以后所有依赖包都会下到这个文件夹里C盘压力骤减。4.3 配置阿里云镜像下载速度立竿见影这一步是整个配置里体验提升最明显的一环同时也是最容易被人忽略的。热搜词里“下载maven”“maven依赖管理”频繁出现恰恰说明很多人都卡在下载环节。Maven默认的中央仓库在国外服务器国内网络拉取依赖包经常速度慢如蜗牛或者下载到一半直接报连接超时。解决办法就是换成国内镜像。在settings.xml里的mirrors标签下添加一个阿里云的镜像配置mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirrormirrorOf填central表示只对中央仓库做镜像镜像不影响你自己配置的其他私服仓库这个写法比粗暴的*更合理。阿里云这个公共仓库相当于把Maven中央仓库存了一份在国内你下载依赖走的就是国内路径速度几乎可以直接拉满。我个人用过很多年稳定性和同步速度都让人放心。如果你是在公司环境工作而且内部有Nexus私服那就不要配阿里云了改成公司私服地址逻辑一样只是url换掉。这个通常由公司的架构师或团队Leader统一发给你。4.4 顺手把JDK编译级别锁定一下settings.xml里的另一个常用配置项是profiles标签下指定JDK版本。不配的话Maven在很多老项目上会默认用JDK 1.5的编译级别导致明明用着JDK 17却疯狂报“无效的源发行版”。在settings.xml的profiles里加上profile idjdk-17/id activation activeByDefaulttrue/activeByDefault jdk17/jdk /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /profile如果你用的是JDK 8就把17全部改成1.8。项目源码编码统一设成UTF-8能避免控制台中文乱码这个经典问题。5. IDEA集成Maven第一次创建项目最容易翻车的地方5.1 别用IDEA内置的Bundled MavenIDEA是自带Maven的很多教程里也直接让你用内置的图省事。但我的经验是IDEA内置的Maven版本通常比较旧而且它不一定跟我们刚才配置的settings.xml联动。你如果用了Bundled Maven最后极有可能出现这种诡异局面命令行里mvn clean package构建一切正常IDEA里一刷新却报依赖找不到。解决办法很简单在IDEA里手动指定我们自己安装的Maven。打开IDEA进入File - SettingsWindows快捷键CtrlAltS左侧菜单搜索框输入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.encodingUTF-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.exampleartifactId是包裹里那个商品的具体型号比如hello-serviceversion是第几代产品比如1.0.0。三个组合在一起就是Maven在仓库里找这个包裹的完整地址。后面你给自己写模块时这个就是唯一坐标不要轻易改动。如果改了依赖它的其他模块也要跟着改一处漏改就是一堆报错。6.2 常见依赖的引入姿势和排查方法比如一个Spring Boot项目pom.xml里通常会先继承父工程parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version relativePath/ /parent然后引入Web支持dependency groupIdorg.springframework.boot/groupId artifactIdspring-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工具窗口双击对应命令就能执行。日常开发最常用的组合是cleaninstall这个组合会把项目编译、测试、打包并安装到本地仓库这样同台机器上其他项目就能引用到最新版本。每当你改了一个公共模块的代码记住先对它执行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没有点OverrideIDEA仍在用自己默认位置下的settings.xml。另外settings.xml文件一旦用带BOM的编码保存XML解析器会把它当成一个不可见字符Maven就会报处理错误或忽略部分配置。一定要用UTF-8无BOM编码保存推荐用IDEA自己的编辑器改settings.xml天然规避这个问题。7.4 多JDK环境下的版本错乱问题如果你电脑上装了多个JDK比如为了维护老项目装了8又为了新项目装了17Maven可能会在构建时报奇怪的编译错误。此时最好确认一下项目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、解决依赖冲突、掌握生命周期指令的灵活组合。到那时候你回头看今天折腾的这些东西会发现一切都值得。