做Java开发绕不开Maven而“Maven安装”这个话题我每年都要在带新人、换电脑、重装系统的时候重新过一遍。Maven本身不复杂但真正折腾人的往往是版本对不上、环境变量不生效、依赖下载超时、IDEA里导入项目一片红色报错这些细节。Maven是一个开源的Java项目构建和依赖管理工具它解决的是项目里成百上千个jar包从哪来、版本怎么控制、项目怎么统一编译和打包的问题。这篇教程我会把下载、安装、配置、验证、集成IDEA的完整流程走一遍还会把每个步骤背后的原因、常见的坑和排查方法一起讲清楚让不同基础的读者都能跟着操作下来。1. 装Maven之前先弄清楚这个工具的价值1.1 Maven是在什么背景下出现的很多新手第一次接触Maven都会有个困惑我直接用IDEA不就能写Java了吗为什么还要单独装一个Maven这个问题的答案要从Java项目的依赖管理说起。早期Java项目管理jar包的方式非常原始团队里会有一个人把需要的jar包统一下载好放到项目下的lib目录里其他人再拷贝到自己电脑上。这么做的问题很明显。首先是体积问题一个项目几十个jar包压缩完也要几十上百兆拷贝和传输很费劲。其次是版本管理混乱同一个jar包在不同电脑上可能被替换成不同版本大家开发时跑得好好的一合并代码就报ClassNotFoundException或者其他诡异错误。最要命的是传递依赖比如你只用了一个工具包它底层又依赖了另外三个jar包这三个jar包还可能互相冲突手动解决起来完全没有尽头。Maven出现以后这套逻辑被彻底改变了。项目里只需要一个pom.xml文件声明需要哪些依赖Maven就会根据坐标从仓库里自动下载jar包并且把依赖关系理顺这就是依赖管理。同时Maven还规定了标准的项目目录结构约定了编译、测试、打包、安装、部署这一整套生命周期开发人员沿着这套规范走项目结构统一了构建流程也标准化了。所以Maven不只是一个“下载工具”它更像一个项目管家从依赖到构建再到发布全程帮你打理。1.2 安装前必须理解的两个核心概念在动手安装之前我建议先理解两个概念本地仓库和远程仓库否则后面配置的时候很容易一头雾水。本地仓库是Maven在你电脑硬盘上开辟的一个目录所有下载过的jar包都会缓存在这里。默认路径是用户目录下的.m2/repository比如Windows下就是C:\Users\你的用户名.m2\repository。Maven每次解析依赖都会先去本地仓库找找不到才会去远程仓库下载下载完再次存入本地仓库。理解这一点非常重要因为很多“我明明加了依赖为什么还是报错”的问题根源就在本地仓库缓存上。远程仓库则是jar包的源。Maven默认使用Apache中央仓库Central Repository但这个仓库服务器在海外国内访问速度不稳定所以安装完Maven的第一件事通常就是配置国内镜像仓库让依赖从国内镜像下载速度能快上好几倍。这个操作在后面的settings.xml配置里会详细讲。先把这几个概念放进脑子里后面每一步配置你会看得更通透。2. 安装前的准备版本选择和下载入口2.1 JDK版本与Maven版本怎么匹配很多人的Maven装不上、启动报错问题不是出在Maven本身而是JDK版本不匹配。Maven本身是用Java写的运行Maven命令必须要有JDK环境而且不同版本的Maven对JDK版本有不同要求。我在实际使用中的经验是对照这张表来选版本Maven版本运行所需JDK典型使用场景3.6.3JDK 1.7及以上老项目、教材和视频课程最常见3.8.8JDK 1.8及以上Spring Boot 2.x项目常用稳定性好3.9.xJDK 8及以上推荐JDK 17新项目、Spring Boot 3.x推荐使用如果你的电脑装的是JDK 1.8那直接用Maven 3.6.3是最稳妥的选择网上资料最多遇到问题也好查。如果电脑是JDK 17或者更高版本就考虑3.9.x。这里要特别提醒一句不要因为追求新版本就盲选版本匹配是关键。我帮同事排查过不少次明明改了环境变量mvn -v就是报错结果一看他电脑上装了三个JDK命令行默认用的版本太低Maven根本起不来。2.2 官方下载入口和文件怎么选Maven的官方网站是maven.apache.org页面排版比较朴素但信息很全。进官网后点击Download菜单往下拉会看到一个Files区域里面列着各个版本的文件下载链接。下载时要注意文件命名。以3.8.8版本为例会看到apache-maven-3.8.8-bin.zip、apache-maven-3.8.8-bin.tar.gz、apache-maven-3.8.8-src.zip等几个文件。我们只需要bin结尾的二进制文件Windows选zip格式Linux和macOS选tar.gz格式。src结尾的是源码包是给想研究Maven源码的人准备的普通使用完全不用管。还有一点要注意的是从3.9.0版本开始Maven官方对下载文件做了拆分bin目录下变成了直接可运行的压缩包不再单独提供“带依赖”的版本所以直接认准bin.zip下载就可以了。不过有一个比较蛋疼的现实问题官方服务器在海外直接从官网下载速度很不稳定有时候一个几十MB的包能下半天。这种情况我一般建议直接走国内镜像站的下载页搜一下“阿里云Maven镜像”或者“清华大学开源软件镜像站”在对应目录里找到apache-maven文件夹下载速度会快很多。2.3 顺手搞清楚Maven仓库的网页入口关于搜索热词里出现的“maven仓库网页版入口”这里顺便说一下。刚才提到的本地仓库是存在于你电脑上的目录远程仓库则是服务器上存放jar包的地方。你如果想手动查询某个依赖的准确坐标groupId、artifactId、version有两个常用入口一个是mvnrepository.com支持直接搜索jar包会列出所有可用版本这个网站应该被每个Java开发者加入书签另一个是阿里云仓库的网页版查询界面可以浏览仓库里的所有构件信息。记住这两个入口对后面处理依赖问题很有帮助。比如你在pom.xml里写了一个依赖IDEA提示Cannot resolve第一步就该去mvnrepository上确认坐标和版本号是否真实存在往往问题就出在这里。3. 环境变量的配置与安装验证3.1 选择合适的解压目录Maven是绿色软件不需要安装程序下载下来解压就能用。但解压到哪个目录是有讲究的。我个人强烈建议放在一个没有空格、没有中文的路径下比如D:\dev\apache-maven-3.8.8。不要直接解压到C盘Program Files目录下面因为Program Files中间有空格有些老旧的构建脚本解析路径时会出问题也不要用中文路径部分Maven插件对中文路径支持不好打包时偶尔会报编码或路径错误。解压完之后你可以看一眼目录结构。里面比较重要的有bin目录存放着mvn可执行脚本conf目录存放着全局配置文件settings.xmllib目录存放Maven运行时需要的jar包。命令行里用的mvn命令其实就是调用了bin目录下的脚本。3.2 配置MAVEN_HOME和PATH环境变量解压完Maven之后要让系统能找到mvn命令就必须配置环境变量。Windows下的操作是右键“此电脑” - 属性 - 高级系统设置 - 环境变量。第一步在系统变量里点击“新建”变量名填MAVEN_HOME变量值填你的Maven解压路径比如D:\dev\apache-maven-3.8.8。第二步在系统变量里找到Path变量双击进入编辑界面点击“新建”输入%MAVEN_HOME%\bin然后确定保存。这里解释一下为什么要配置MAVEN_HOME而不是直接把bin目录全路径写进Path。MAVEN_HOME相当于是一个全局的变量引用以后你要升级Maven版本或者在同一台电脑上切换多个版本只需要修改MAVEN_HOME这一个变量的值Path里的内容完全不用动。这个做法对IDEA也很友好后续集成时IDEA可以直接通过MAVEN_HOME识别Maven位置。macOS和Linux上的配置逻辑一样只是改的文件不同。macOS是编辑~/.zshrc或~/.bash_profile在里面加两行export MAVEN_HOME/你的路径/apache-maven-3.8.8和export PATH$MAVEN_HOME/bin:$PATH然后source ~/.zshrc让它生效。Linux则视shell而定Ubuntu默认的bash就编辑~/.bashrc。如果你在macOS上不想手动配置也可以直接用Homebrew执行brew install maven一条命令就搞定但对代理、镜像等配置的控制粒度会差一些建议还是手动配。3.3 命令行验证是否安装成功配置完环境变量后最关键的一步就是验证。注意一定不要用配置环境变量之前就打开的命令行窗口因为环境变量只在窗口启动时加载一次。你需要重新打开一个新的cmd窗口或者PowerShell然后输入mvn -v如果输出类似下面的信息说明安装成功了Apache Maven 3.8.8 (XXX) Maven home: D:\dev\apache-maven-3.8.8 Java version: 1.8.0_XXX, vendor: Oracle Corporation Java home: D:\dev\jdk1.8.0_XXX Default locale: zh_CN, platform encoding: GBK这条输出里有两个信息要特别关注Maven home是否指向你刚才配置的目录Java version是否和你的JDK版本吻合。如果Java version显示的是低版本JDK而你明明装了更高的JDK那就要去检查环境变量里的JAVA_HOME是不是指错了因为Maven启动时优先读JAVA_HOME。这也是整个安装过程中最常见的一个坑我在第6章会单独展开。4. settings.xml才是真正决定Maven好不好用的文件4.1 找到settings.xml并理解它的作用范围Maven安装目录下的conf/settings.xml是全局配置文件它决定了Maven在“这台电脑”上的一系列行为。另外还有一个用户级配置文件默认位于~/.m2/settings.xmlMaven启动时会优先读取用户级配置如果用户级配置不存在才回落到全局配置。在实际工作中我更推荐使用用户级配置也就是把conf目录下的settings.xml复制一份到.m2目录下然后改动.m2里的那份。这样做的好处是全局的那份始终保留原始状态以后排查问题时可以拿原始配置做对照而且不同用户登录同一台电脑时可以有各自独立的配置。复制操作很简单在用户目录下找到.m2文件夹如果不存在就新建一个把conf/settings.xml复制进去后续的所有修改都针对这个文件进行。4.2 修改本地仓库路径settings.xml里第一个值得改的就是本地仓库路径。默认的~/.m2/repository位于C盘随着项目越做越多本地仓库会轻松膨胀到几个GB甚至十几个GB全堆在C盘会让系统盘不堪重负。我习惯把本地仓库统一放到单独的数据盘比如Windows下改成D:/dev/maven-repomacOS下改成/Users/你的用户名/Dev/maven-repo。在settings.xml里找到这一段把默认的路径替换掉localRepositoryD:/dev/maven-repo/localRepository有同学可能会问为什么要单独配置而不是用默认路径除了节省C盘空间之外还有一个更现实的原因重装系统或重装IDEA之后默认的.m2目录经常被清理掉而Maven本地仓库里缓存了几百个jar包一旦清了就要重新下载半天时间就这么浪费了。放在一个固定的数据盘目录里重装完系统把路径一填所有依赖缓存都还在立刻就能继续干活。4.3 配置阿里云镜像和多个镜像本地仓库配置完接下来是重头戏配置远程镜像仓库。默认情况下Maven从中央仓库下载依赖但这个仓库服务器在海外如果不配置镜像下载一个Spring Boot依赖可能要等几分钟遇到网络波动还会直接断掉报各种连接超时错误。国内最常用的是阿里云公共仓库。在settings.xml的mirrors节点里加上如下配置mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors这段配置的意思是拦截对中央仓库的请求转发到阿里云的public仓库。阿里云的public仓库聚合了中央仓库、JCenter以及部分公共仓库的内容覆盖日常开发已经足够了。如果你的项目里用了一些只在特定仓库里存在的依赖还可以配置多个镜像用多个mirror节点并列即可。不过在配置多个镜像时要注意mirrorOf的匹配规则这个很关键我在下面单独讲。4.4 mirrorOf的匹配规则和优先级mirrorOf是一个字符串用来声明当前镜像要拦截哪些仓库的请求。常见的几种写法含义完全不同* 匹配所有仓库所有请求都走这个镜像 central 只匹配中央仓库 repo1,repo2 匹配多个指定仓库 external:* 匹配除本地仓库之外的所有远程仓库如果配置了多个mirrorMaven的匹配逻辑是按顺序查找第一个匹配当前请求仓库的mirror找到就使用它后面的不再生效。这一点很关键很多人配置了多个镜像却发现某个依赖一直在某个慢仓库上拉取就是因为第一个mirror的mirrorOf写的是*把所有请求都拦截走了。我个人的建议是如果只是做常规Java开发一个阿里云mirror配mirrorOf为central就够了简单直接。如果你确定了要用多个仓库就要设计好匹配顺序不要让两个mirror的mirrorOf范围重叠产生歧义。比如要同时使用阿里云和一个私服仓库可以让阿里云匹配central私服匹配私服仓库的idmirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror mirror idcompany-nexus/id mirrorOfcompany-repo/mirrorOf urlhttp://nexus.company.local/repository/maven-public//url /mirror /mirrors这样配置的好处是互不干扰两个镜像各司其职不会出现“所有请求都跑到私服去”的尴尬情况。4.5 顺带配置JDK编译版本和HTTP代理提到settings.xml有两个配置项也值得顺手改一下。一个是profile里设定的JDK版本。如果项目使用的是JDK 1.8而环境中存在多个JDK版本Maven默认编译时可能不会盯到正确的编译级别导致项目里出现source/target版本相关的编译报错。在settings.xml的profiles节点里加一段固定编译级别配置profiles profile idjdk-1.8/id activation activeByDefaulttrue/activeByDefault jdk1.8/jdk /activation properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target maven.compiler.compilerVersion1.8/maven.compiler.compilerVersion /properties /profile /profiles另一个是HTTP代理配置。如果你在公司内网环境访问外网必须通过代理那就要在settings.xml里加proxies节点。具体host和port要问公司网络管理员这里就不展开了。需要注意如果IDEA连带Maven一起使用IDEA里的HTTP代理设置有时会覆盖settings.xml里的配置两边都可能要改排查代理问题的时候要记住这一点。5. 集成到IDEA让Maven为你的日常开发服务5.1 让IDEA使用本机Maven而不是内置版本IDEA自带一个Maven默认配置下你新建Spring Boot项目就能直接跑起来。但我不推荐使用自带版本因为IDEA内置的Maven和你命令行里用的版本很可能不一致这会导致一个很尴尬的局面命令行里mvn clean install跑得好好的IDEA里刷新依赖却报错或者反过来。保持工具链一致能省掉大量无谓的调试时间。打开IDEA进入File - SettingsMac上是IntelliJ IDEA - Preferences依次找到Build, Execution, Deployment - Build Tools - Maven。这里有三个核心配置项第一项Maven home path选择你本机安装的Maven目录也就是解压后的apache-maven-3.8.8目录。第二项User settings file把右侧的Override勾选上然后选择你的settings.xml文件路径IDEA读到这里配置后会自动识别出localRepository路径。第三项Local repository勾选Override确认路径指向你自己的本地仓库。设置完成之后点击ApplyIDEA会自动Index一次这个过程就是扫描本地仓库的jar包让代码提示和依赖解析都基于本地缓存。另外在Maven设置界面下方有一个Runner选项进入后可以把VM Options设置为-Dmaven.wagon.http.ssl.insecuretrue -Dmaven.wagon.http.ssl.allowalltrue -Dmaven.wagon.http.ssl.ignore.validity.datestrue这三行配置的含义是让Maven在通过HTTPS协议下载依赖时不校验证书。虽然从安全角度讲不算“最佳实践”但在内网私服经常自签证书的开发场景下这确实是最快速解决“证书信任问题”的办法。公网开发时我一般会加内网私服没有正规证书时不加这行配置Maven很可能直接报PKIX证书相关错误导致所有依赖都下载失败。5.2 在IDEA里执行生命周期命令配置好Maven之后IDEA右侧会出现一个Maven工具窗口。展开之后有两个核心区域Lifecycle和Dependencies。Lifecycle里是Maven的构建生命周期命令按执行顺序依次是validate、compile、test、package、verify、install、clean。日常开发中最常用的组合是clean和install。手动执行时我一般这样用先在Lifecycle里双击clean让项目删掉之前的编译产物再双击install做完整编译、打包并安装到本地仓库。在命令行里对应的命令是mvn clean install -DskipTests-DskipTests的意思是跳过测试。如果项目里的单元测试很耗时或者测试环境还没有准备好用这个参数能明显加快构建速度。需要注意-DskipTests只是不执行测试测试代码仍然会编译如果你想连测试代码编译都跳过用-Dmaven.test.skiptrue这个参数更彻底。还有一种常见场景是依赖冲突排查在IDEA的Maven工具窗口中选中某个模块执行依赖分析功能可以看到当前模块的完整依赖树。命令行对应的命令是mvn dependency:tree在实际工作中比从代码里一行一行找依赖来源高效得多。5.3 导入项目时的常见问题新导入一个Maven项目时IDEA识别pom.xml之后会自动刷新依赖。如果遇到需要的jar包已在本地仓库存在但项目里还是标红在IDEA里点一下Maven工具窗口的刷新按钮就能触发重新加载。有一次我改了本地仓库路径项目里所有依赖全部飘红折腾了好一会才意识到IDEA里的Local repository还指向旧的.m2目录手动改掉之后点刷新一切恢复正常。另外idea配置maven的时候还有一个小习惯我会打开IDEA的Settings - Build Tools - Maven - Importing里的JDK for importer设置把它也改成和项目一致的JDK版本。这样可以避免IDEA在导入Maven项目时用了一个不匹配的JDK来解析pom导致部分插件和依赖被判定为不兼容进而出现只有你遇到、同事都正常的诡异问题。6. 常见问题与排查技巧实录6.1 环境变量明明配好了mvn -v还是提示找不到命令这个问题的排查思路有固定的顺序。第一步先确认你是否重新打开了命令行窗口Windows下配置完环境变量旧窗口不会自动刷新一定要新开cmd。第二步在命令行里执行echo %MAVEN_HOME%看输出是否是预期的Maven路径如果输出为空说明MAVEN_HOME变量没有配置成功回到环境变量设置界面检查变量名是否拼写正确。第三步检查Path变量里是否包含了%MAVEN_HOME%\bin注意Windows的PATH中路径分隔符是分号不要把分隔符给弄丢了。还有一类情况比较隐蔽电脑上装了多个版本的Maven或者有其他软件自动修改了PATH环境变量导致cmd里执行mvn -v时命中的是旧版本。遇到这种情况在命令行里执行where mvnWindows会列出所有被找到的mvn命令路径按顺序返回的第一个就是实际命中的版本。看到结果之后你就能判断是不是路径优先级的问题。6.2 依赖下载特别慢、卡住或者报传输超时依赖下载慢绝大多数情况下是镜像配置没有生效。先检查settings.xml里localRepository指向的目录看里面是不是出现了一堆lastUpdated后缀的文件。出现lastUpdated文件基本可以断定Maven在下载某个依赖时失败了并且把失败状态记录了下来后续构建会直接跳过重新下载哪怕网络已经恢复正常。处理办法是先把这些lastUpdated文件清理掉再执行一次强制更新。命令行方式mvn clean install -U-U参数会强制拉取远程仓库忽略本地缓存的时间戳。如果想清得干净一点可以直接在本地仓库目录下搜索所有lastUpdated文件并删除find ~/.m2/repository -name *.lastUpdated -exec rm -f {} \;Windows下没有find命令可以用IDEA的搜索功能打开本地仓库手动搜*.lastUpdated删除或者借助Everything这类文件搜索工具批量操作。清理完再重新构建通常就能恢复正常。这个坑我踩过很多次切记lastUpdated文件是“坏缓存”的标志不是正常文件。6.3 Cannot resolve类报错以mysql-connector-j为例搜索热词里有一条很典型Cannot resolve com.mysql:mysql-connector-j:release。这种报错几乎可以断定是版本号写法出了问题。Maven的依赖声明里version是必填项必须是一个明确的版本号比如8.0.33。有些人从Gradle项目转过来习惯性地写release或者latest这样的特殊标签Gradle能识别Maven却不会去帮你解析于是IDEA就报Cannot resolve。还有一种常见写法是把版本号抽成properties变量properties mysql.version8.0.33/mysql.version /properties dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version${mysql.version}/version /dependency如果properties里没有定义mysql.version这个变量同样会报Cannot resolve。排查方法就是去mvnrepository查一下确认坐标正确再确认变量是否定义这两步走完90%的Cannot resolve都能解决。6.4 SSL证书报错PKIX path building failed依赖能正常列出但下载时报PKIX path building failed证书信任链断了。这类问题的根源在于目标仓库的HTTPS证书不被当前JDK信任。通常发生在私服、内网仓库或者一些证书配置不规范的镜像站点。快速解法是在Maven启动参数里加上前面提到的三行-Dmaven.wagon.http.ssl.insecure等参数关闭证书校验。如果是在命令行里执行可以在命令前直接加参数mvn clean install -Dmaven.wagon.http.ssl.insecuretrue -Dmaven.wagon.http.ssl.allowalltrue长期方案是把仓库的证书导入JDK的cacerts证书库。具体操作是下载证书文件执行keytool -import -alias 仓库别名 -keystore JDK目录/jre/lib/security/cacerts -file 证书文件。这个办法比较繁琐但更正规。在日常开发场景下我更多会先确认当前Maven和JDK版本是否过旧有时候升级到新版Maven旧的证书问题会自动消失。写到这里Maven从下载到安装、配置、集成、排错的全流程就梳理完了。我个人在实际操作中最大的体会是Maven安装过程中出现的报错绝大部分不是因为你“少装了某个东西”而是版本匹配、路径配置、镜像策略这几件事没有对齐。如果你把JDK版本、MAVEN_HOME、本地仓库路径、阿里云镜像、IDEA里的三个配置项按顺序核对一遍这套环境基本就不会再出幺蛾子。最后分享一个小技巧如果你同时接多个公司的项目每家公司的私服地址和镜像策略都不一样建议不要频繁改同一份settings.xml而是把不同公司的配置分别命名为settings-companyA.xml、settings-companyB.xml需要用哪份就在IDEA里切换哪份这样既能保证切项目时的速度也不会把配置搞乱。