昨天组里来了个新同事工位还没坐热IDEA里Spring Boot工程已经飘红一片右下角反复跳那行熟悉的英文download from maven failed。我过去扫了一眼本地仓库里全是密密麻麻的.lastUpdated临时文件进度条纹丝不动。这种场面我一年能见十几次最后的根因翻来覆去无非那么几类Maven本身装得不对、settings.xml里的镜像没配、IDEA没指到正确的配置文件、依赖下载到一半把本地仓库弄脏了。这篇文章不是那种“十分钟速成”的安装教程而是把“从零装好Maven并让它真正跑起来”这条路上的坑深度趟一遍。标题是Maven02我们上一个阶段聊过Maven的基本概念和工作原理这篇重点放在安装配置、环境变量、镜像仓库、IDE集成以及最让人头疼的依赖报错排查上。适合刚接触Maven的新人、换了新电脑准备重配环境的老手以及在IDEA里被依赖标红折磨到怀疑人生的朋友。1. Maven到底在替你干什么一套坐标背后的完整链路很多人把Maven理解成“jar包下载器”不能说全错但理解得太窄了。Maven最初的核心确实是依赖管理但它真正的价值在于构建生命周期管理。如果你只把它当成“下载完就完事”的工具后面遇到莫名其妙的报错根本无从下手。1.1 坐标、仓库与pom.xml的三角关系先看一个最普通的依赖声明dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version2.7.18/version /dependencygroupId是组织标识artifactId是模块名称version是版本号。这三个坐标唯一确定一个jar包。Maven拿到坐标之后去哪里找按顺序覆盖三个地方本地仓库、远程镜像仓库、中央仓库。本地仓库默认在用户目录下的.m2/repository所有下载过的依赖都会缓存到这里。远程仓库是你自己配置的镜像或公司私服。中央仓库是Maven官方服务器地址在国外直接访问速度不稳定——所以国内团队几乎都会配一个阿里云镜像。用生活化的方式理解中央仓库是远在国外的总店本地仓库是你家冰箱镜像仓库是楼下便利店。Maven找jar包先翻冰箱没有再去便利店便利店还没有才考虑跨国采购。这里有个新手最容易忽略的点IDEA里如果指定了本地仓库路径但这个路径和命令行默认路径不一致就会出现“IDEA里明明有依赖跑到命令行就全要重新下载”的现象。我建议所有地方都沿用同一个本地仓库目录别在IDEA里单独改来改去。1.2 生命周期mvn install到底执行了多少步执行mvn clean install时Maven并不是“先删掉target再打一个包”这么简单。它内部有一个固定的生命周期阶段序列默认都会依次执行阶段作用validate校验项目结构是否完整compile编译src/main/java下的源码test运行src/test/java下的单元测试package打成jar/war包verify运行集成测试并检查校验结果install把构建产物安装到本地仓库供其他项目引用注意直接执行package时test阶段也会跑因为package在test后面。如果只想打包跳过测试常用的命令是mvn clean package -DskipTests或者用-Dmaven.test.skiptrue连测试代码一起跳过编译。很多人在CI上构建不稳定多半就是单元测试里有环境依赖。每个阶段背后都有对应的Maven插件在干活——编译用的是maven-compiler-plugin打包用的是maven-surefire-plugin。这些插件本身也是从仓库下载的所以第一次执行构建会特别慢因为除了项目依赖Maven还要把一堆插件拉下来。1.3 settings.xml是全局配置中心Maven有两个层级的配置文件。全局配置在Maven安装目录下的conf/settings.xml用户配置在~/.m2/settings.xml。规则是用户配置覆盖全局配置。当你在IDEA里看到“User settings file”指向了Maven安装目录里的默认settings.xml那就说明你根本没用上自己写的镜像配置。所有关于仓库镜像、本地仓库路径、代理、私服认证等配置全部集中在settings.xml里。这篇文章后半部分讲的镜像配置和依赖报错几乎都是围绕这个文件展开的。建议先备份一份原始的settings.xml改坏了随时能还原。2. 下载安装与环境变量版本选错会让排查方向跑偏Maven的安装步骤看起来就是“解压配环境变量”但实际工作中有一半的依赖问题其实是因为版本和JDK不匹配引起的。版本选错后面排查一整天都找不到头绪。2.1 版本和JDK怎么搭配别随手拿最新版访问Maven官网下载页面时有几个主要分支3.6.x、3.8.x、3.9.x。不同版本对JDK的要求不一样建议按项目实际情况选择而不是永远拿最新版。Maven版本对应JDK典型使用场景Maven 3.6.3JDK 8老项目、企业存量项目最稳的组合Maven 3.8.xJDK 8/11Spring Boot 2.x项目的常见标配Maven 3.9.xJDK 8及以上新项目、Spring Boot 3.x推荐使用判断环境是否匹配先看JAVA_HOME指向哪个JDK版本再看Maven版本。如果JDK版本过新而Maven版本太老可能直接报“Unsupported major.minor version”反过来JDK太老而Maven太新也会因为Maven运行时需要高版本Java而启动失败。下载的时候注意选文件Windows用户下载apache-maven-x.x.x-bin.zipLinux/macOS用户下载apache-maven-x.x.x-bin.tar.gz。千万别下-src.zip那是源码包不是可运行的二进制发行版。2.2 环境变量MAVEN_HOME、PATH与JAVA_HOME的三角关系Maven本身是Java写的一个命令行工具运行时必须有JAVA_HOME环境变量。没有JAVA_HOME的话Maven启动脚本连Java虚拟机都找不到。所以安装顺序通常是先装JDK配置JAVA_HOME再解压Maven配置MAVEN_HOME。Windows下配置步骤新建系统环境变量MAVEN_HOME值为Maven解压目录比如D:\apache-maven-3.9.6。编辑系统变量Path新增%MAVEN_HOME%\bin。重新打开CMD窗口执行mvn -v验证。macOS和Linux下在~/.zshrc或~/.bashrc里加上export MAVEN_HOME/opt/apache-maven-3.9.6 export PATH$PATH:$MAVEN_HOME/bin然后执行source ~/.zshrc让配置生效。这里有个非常经典的坑Windows下改了环境变量后已经打开的命令行窗口不会自动刷新必须重新开一个。很多人在旧的CMD里敲mvn -v发现提示不是内部命令就以为配置失败其实只是窗口没重开。另外Path里不要手滑在%MAVEN_HOME%\bin末尾加多余的分号或空格这种隐藏字符会让命令找不到。2.3 老系统Windows 7和国产系统的安装特例“Maven有麒麟版吗”这个热搜词很有意思——Maven是纯Java程序本质上不区分操作系统和CPU架构只要目标机器上有对应版本的JDK解压就能跑。麒麟这类国产Linux系统上安装Maven流程和Linux完全一样装JDK、解压、设环境变量没有任何所谓“麒麟专用版”。Windows 7是个更容易踩坑的场景。老系统默认没有启用TLS 1.2而新版Maven在下载依赖时需要走HTTPS连接如果系统TLS版本支持不到位会一直报“Could not transfer artifact”或证书错误。我的建议是Windows 7机器优先使用Maven 3.6.3 JDK 8的组合同时让系统安装微软的TLS 1.2补丁。别尝试在Win7上强行跑最新版Maven浪费的时间远远超过它带来的好处。3. 镜像仓库配置阿里云之外的稳定方案配置镜像应该是整个Maven使用中性价比最高的一步。很多人从中央仓库下载依赖卡到怀疑人生配好镜像后从几分钟缩短到几十秒。但镜像配置也有不少细节配错了不是不生效就是私服依赖全被拦了。3.1 阿里云镜像标准配置先用最保险的方式跑通在~/.m2/settings.xml的mirrors标签下加这样一段mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror这段配置的作用把对中央仓库的访问全部重定向到阿里云的public仓库。public仓库聚合了中央仓库和JCenter的绝大多数依赖日常项目足够用了。配置完成后验证是否生效不要打开IDEA看先在命令行执行mvn help:effective-settings这个命令会输出最终生效的settings.xml内容。如果mirror段存在说明配置已经被读取。再用mvn dependency:resolve实际拉一次依赖观察输出里的下载地址是不是maven.aliyun.com。3.2 mirrorOf不只是一个仓库名几个取值到底在控制什么mirrorOf是最容易写错的地方。它的作用是声明“我要拦截哪些仓库请求”常用写法见下表写法含义适用场景central只拦中央仓库最安全适合配置了私服的项目*拦截所有仓库国内环境强加速但会拦截公司私服external:*拦截除localhost和file协议外的所有仓库兼顾私服本机部署repo1,repo2只拦指定id的仓库多镜像精确分流很多教程直接让你写*我建议谨慎。如果公司内部有Nexus私服写了*意味着所有私服请求也被抢到阿里云去了那项目里特有的内部依赖全部下载不了。更好的做法是用central或明确列出仓库id。另外多个mirror同时存在时Maven只会使用第一个匹配当前仓库的mirror后面的同类配置不会生效。这个特性导致“我配了五个镜像结果只有第一个起作用”的现象很普遍。3.3 多镜像配置的正确姿势当阿里云缺某个依赖想加华为云或腾讯云作为补充时正确的做法是让不同镜像负责不同仓库id而不是都写在mirror里。常见的多镜像配置mirrors mirror idaliyun-public/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror mirror idhuaweicloud/id mirrorOfspring-milestones/mirrorOf urlhttps://repo.huaweicloud.com/repository/maven//url /mirror /mirrors如果某个依赖连公共镜像都没有就需要在pom.xml里单独配置repository让它去指定的仓库查找。mirror和repository的区别在于mirror是“拦截并改写到统一地址”repository是在pom.xml里声明“额外去哪些仓库找”。两者不冲突但最好先用mirror统一入口再在pom.xml里加例外仓库。3.4 配了镜像还是不生效三个排查方向按我排查过的经验镜像“不生效”90%出在下面三个原因settings.xml文件位置不对。你改了Maven安装目录conf/settings.xml但IDEA实际使用的是~/.m2/settings.xml或者反过来命令行用的是用户settingsIDEA里却Override指到了旧文件。配置没在mirrors标签里。有人手滑把mirror写到了profiles或pluginRepositories里Maven直接忽略。仓库id和mirrorOf不匹配。下载失败的坐标来自某个仓库id比如nexus但mirrorOf只写了central自然不会拦那个仓库。检查时优先用mvn help:effective-settings看结果而不是反复猜“是不是IDEA缓存了”。IDEA确实有配置缓存但命令行不会骗人。4. IDE集成IDEA、Cursor、Trae里的Maven“抽风”现场用命令行跑通之后还要让Maven在IDE里顺滑工作。这一节的常见问题基本都来自热搜词idea配置maven、maven工具栏不见了、idea创建maven工程src目录不完整、cursor怎么配置java和maven。每个我都实际处理过。4.1 IDEA里三个必改配置别再让内置Maven跟你打架打开Settings → Build, Execution, Deployment → Build Tools → Maven重点看三块Maven home path这里默认可能是IDEA自带的Bundled (Maven 3)。我建议改成你自己安装的Maven目录。好处是命令行和IDE使用同一套Maven行为完全一致不会出现“命令行打包成功、IDEA里却报插件找不到”这种奇怪差异。User settings file勾选Override指向~/.m2/settings.xml。不勾选的话IDEA有可能读的是安装目录里的默认配置你配的阿里云镜像全部白搭。Local repository确认指向正确的本地仓库路径。如果你之前已经下载过不少依赖这个路径不能错推荐一律使用~/.m2/repository。改完配置后点IDEA右侧Maven工具窗口里的刷新按钮Reload All Maven Projects让依赖重新解析。很多人改完配置发现依赖还是标红就是忘了触发重新加载。4.2 Maven工具栏不见了去哪找Maven工具窗口消失最常见的原因是项目没有被正确识别为Maven工程而不是IDEA坏了。排查顺序看项目里有没有pom.xml文件。没有的话这个项目压根不是Maven项目需要在项目结构中Add Framework Support选择Maven才会自动生成pom.xml。如果pom.xml存在但IDEA没识别右键pom.xml选择Add as Maven Project工具窗口就会回来。从顶部菜单栏进入View → Tool Windows → Maven手动召唤。如果还是没有去Settings → Plugins搜索Maven相关插件确认没有被误禁用。还有一个比较坑的场景IDEA的Maven工具窗口里啥都有但双击某个依赖时没有下载动作状态一直显示“Downloading…”然后卡死。这种情况多半是网络请求走了错误代理去Settings → Appearance Behavior → System Settings → HTTP Proxy检查一下选No proxy或正确的自动检测确认之前没有手动填一个失效的代理地址。4.3 新建Maven工程src目录不完整用IDEA创建Maven工程时如果选了不用的骨架模板经常出现只有src目录但里面没有src/main/java、src/test/java这些标准目录的情况。这不是工程坏了而是maven-archetype生成的模板本来就不全。解决办法手动创建目录结构然后在src/main/java目录上右键选择Mark Directory as → Sources Root对src/test/java同样操作标记为Test Sources Root。图标会从黄色变成蓝色或绿色IDEA才真正把它们识别成源码目录。以后再新建只需创建一次这套结构会记录在.idea里。如果你希望IDEA默认把Maven相关配置固定下来可以在配置完Maven后在Settings窗口底部找Save as Default相关入口新项目就会继承当前设置。4.4 Cursor、Trae这类VS Code系工具的Maven配置很多人以为只有IDEA需要配Maven其实Cursor、Trae这类基于VS Code内核的编辑器也要配。它们没有IDEA那样直接的Maven工具窗口通常依赖扩展比如Maven for Java或vscode-maven。装好扩展之后在编辑器的settings.json里加上{ maven.executable.path: /opt/apache-maven-3.9.6/bin/mvn, maven.settings.file: /root/.m2/settings.xml }这两个配置分别指定Maven可执行文件和settings.xml位置。不指定的情况下扩展会自己找PATH里的mvn但经常因为PATH不确定导致找不到。Cursor这类编辑器还有个实际用法直接用它的终端跑Maven命令。报错信息比某些IDE的图形界面显示得更完整排查起来反而舒服。它内置的AI辅助还能根据终端输出直接给出下一步排查建议让“配置Maven”这件事门槛低了很多。5. 依赖报错从“download from maven failed”开始的完整排查链路依赖报错是Maven使用中最高频的痛点。热搜词里“intellij idea sqlserver jdbc 自动下载 download from maven failed”这种长尾需求本质就是依赖没拉下来。很多人一看到failed就开始百度其实正确的做法是沿着报错链路一层层定位。5.1 先看报错里的坐标和URL而不是急着改配置几乎所有下载失败都会在日志里告诉你具体坐标。比如Could not transfer artifact com.microsoft.sqlserver:mssql-jdbc:jar:9.4.1.jre8 from/to central (https://repo1.maven.org/maven2/): ...这里的mssql-jdbc:jar:9.4.1.jre8就是目标坐标repo1.maven.org是实际请求的仓库地址。这个URL本身是最重要的线索。把它复制到浏览器里访问如果浏览器都打不开说明网络层面有问题去检查代理和DNS如果浏览器秒开、命令行却失败那就是Maven侧的仓库配置问题。浏览器能访问但依赖下载失败常见原因就是镜像没生效或者镜像本身没同步这个文件。新版Maven在settings.xml里如果没有正确配置阿里云镜像请求会走去中央仓库下载速度慢大文件容易超时失败。所以排查第一步永远是确认实际请求地址是不是你预期中的镜像。5.2 本地仓库里成堆的.lastUpdated文件看不见的毒药在本地仓库的失败目录下经常会看到大量以.lastUpdated结尾的文件。这些是Maven在下载失败后留下的标记只要存在Maven在默认更新策略下会认为“这个版本刚下载失败过不必重试”于是你又反复触发下载它又反复跳过。处理方法很简单手动删掉这些标记文件。可以在仓库目录下执行find ~/.m2/repository -name *.lastUpdated -type f -delete也可以不删除直接在下载时加强制更新参数mvn clean install -U-U参数会让Maven强制检查并刷新快照和失败记录。但有时IDEA图形界面的Reload不会彻底清除标记命令行更靠谱。删除后重新执行依赖解析之前一直失败的依赖往往就能顺利拉下来。5.3 依赖标红与传递依赖冲突的处理顺序依赖标红不一定都是下载失败也可能是版本冲突或依赖传递问题。一个项目里A依赖B的1.0版C又依赖B的2.0版Maven会按“最近优先”原则选择一个版本如果选出来的版本和某个API不兼容编译就会报错IDEA里表现为某段代码标红。查询冲突用mvn dependency:tree输出里能看到某个依赖到底是从哪条链路引入的。要排除某条传递依赖在pom.xml里dependency groupIdcom.example/groupId artifactIdapp/artifactId version1.0/version exclusions exclusion groupIdcom.example/groupId artifactIdconflict-lib/artifactId /exclusion /exclusions /dependency要全局锁定版本用dependencyManagement项目还会统一管理所有子模块的依赖版本避免每个子pom各自为政。这个机制最适合多模块项目处理不同模块间的版本统一。5.4 zstd-jni这类带本地库的依赖为什么容易卡热搜词里有“maven仓库下载zstd”其实很多项目里是引入了com.github.luben:zstd-jni这个依赖。它里面包含各个平台的本地native库通过classifier区分不同操作系统版本导致下载的artifact数量多、体积大。如果当前镜像仓库没有缓存完整的文件列表下载时就容易超时失败。另外IDEA较新的版本在拉取部分依赖时会尝试协商zstd压缩传输日志里出现类似“Downloading via zstd”的字样不用慌这只是Maven客户端和服务端之间的传输协商失败后会退回普通压缩格式。关键还是要保证网络通畅并让本地仓库里残留的失败标记清除干净不要让它停在半成功状态。遇到这类大体积依赖如果怎么都下不全可以给IDEA的Runner增加更长的网络超时时间-Dmaven.wagon.http.connectionTimeout180000 -Dmaven.wagon.http.readTimeout180000放在Settings → Build, Execution, Deployment → Build Tools → Maven → Runner → VM Options里。这个方法也适用于其他大jar包反复下载超时的场景。6. 用命令行做最终验收mvn clean install一次通过配置了镜像、把IDE也理顺之后最后一步是用命令行做一次完整的构建验收。我自己的习惯是不管改了什么配置先跑一遍mvn clean install确认构建从零开始能通过再打开IDEA干别的。命令行通过的构建到IDEA里大概率没问题命令行失败的时候IDEA里再折腾也都是白费功夫。6.1 为什么优先用命令行而不是直接看IDEIDE的依赖解析是有缓存的有时候settings.xml改了半天IDE里的错误标记还留在界面上误导你继续排查实际上命令行已经构建成功了。命令行是Maven最原始、最直接的接口报错信息不像IDE有时会截断完整的堆栈和下载地址都会打出来。环境变量和settings.xml按最基础的方式生效能直接暴露你配置文件里的问题。跑一次干净构建等于验证了本地仓库、镜像、插件、生命周期所有环节。命令行的失败信息里最典型的几类直接对应不同环节报错关键词对应问题优先排查方向Could not transfer artifact网络或仓库配置镜像URL、代理、浏览器是否能访问Non-resolvable import POM父POM或依赖POM缺失检查坐标版本、私服配置Failed to execute goal org.apache.maven.plugins插件执行失败看具体插件、JDK版本、内存参数BUILD FAILURE测试失败单元测试未通过本地跑测试确认用例环境Unsupported major.minor versionJDK与Maven版本不匹配检查JAVA_HOME和Maven要求6.2 第一次完整构建会经历什么第一次执行mvn clean install时控制台会刷几分钟的下载日志。这是正常现象。Maven要下载的不是只有项目依赖还有大量构建插件比如clean插件、compiler插件、surefire插件、jar插件。这些插件默认也是从你配置的镜像拉取镜像越好初始构建越快。如果你配置了阿里云镜像下载速度通常可以接受。看到BUILD SUCCESS才算真正完成。有些人看到一段WARNING就以为失败了其实Maven的警告很常见比如“The POM for xxx is invalid”或“deprecation warning”这类警告只要没有[ERROR]都不影响产物生成。构建产物的位置在target/目录下install之后还会把jar包安装到本地仓库供同一个机器上的其他项目引用。6.3 几个值得长期坚持的经验这套流程跑熟了之后有几个经验我觉得比任何文档都实用。第一settings.xml一定要备份。我经历过一次手滑把localRepository写错路径结果Maven把依赖当成全新下载硬盘空间几乎被挤爆。现在我的~/.m2/settings.xml后面永远放一份settings.xml.bak。第二本地仓库别放C盘。Windows用户如果把默认的本地仓库留在用户目录一个跑了两年的项目依赖动不动就几个GB系统盘不够用的日子很难受。改localRepository路径到D盘或E盘一劳永逸。第三提交代码前跑一次命令行构建。IDE里编译通过不代表干净环境能构建成功。依赖冲突、插件缺失这种问题在命令行下暴露得最彻底。自己主动先撞见总比CI上撞见强。第四看到BUILD SUCCESS之后先别急着关终端。把输出往上翻看看有没有明显的WARNING顺手处理掉多余的废弃依赖提醒项目维护成本会越来越低。最后再分享一个小技巧说一个我最近常用的习惯不管在IDEA里点了多少次Reload遇到依赖相关的问题我都会先执行一遍mvn help:effective-settings再执行mvn dependency:resolve -U。两步加起来不到一分钟但能明确告诉我“Maven自己认为的最终配置是什么”和“依赖实际下载是否成功”。这比在IDE图形界面里反复猜测可靠得多。Maven这个工具没什么高深莫测的核心就是坐标、仓库、生命周期三个概念加上settings.xml一个配置文件。把环境变量和镜像配好再学会找出下载失败的URL绝大多数问题都能自己解决。剩下的就是多踩几次坑、多归纳几套命令下次遇到相同的报错看一眼输出就能定位到根因。
Maven从安装到依赖报错排查：镜像仓库、settings.xml与IDEA配置详解
昨天组里来了个新同事工位还没坐热IDEA里Spring Boot工程已经飘红一片右下角反复跳那行熟悉的英文download from maven failed。我过去扫了一眼本地仓库里全是密密麻麻的.lastUpdated临时文件进度条纹丝不动。这种场面我一年能见十几次最后的根因翻来覆去无非那么几类Maven本身装得不对、settings.xml里的镜像没配、IDEA没指到正确的配置文件、依赖下载到一半把本地仓库弄脏了。这篇文章不是那种“十分钟速成”的安装教程而是把“从零装好Maven并让它真正跑起来”这条路上的坑深度趟一遍。标题是Maven02我们上一个阶段聊过Maven的基本概念和工作原理这篇重点放在安装配置、环境变量、镜像仓库、IDE集成以及最让人头疼的依赖报错排查上。适合刚接触Maven的新人、换了新电脑准备重配环境的老手以及在IDEA里被依赖标红折磨到怀疑人生的朋友。1. Maven到底在替你干什么一套坐标背后的完整链路很多人把Maven理解成“jar包下载器”不能说全错但理解得太窄了。Maven最初的核心确实是依赖管理但它真正的价值在于构建生命周期管理。如果你只把它当成“下载完就完事”的工具后面遇到莫名其妙的报错根本无从下手。1.1 坐标、仓库与pom.xml的三角关系先看一个最普通的依赖声明dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version2.7.18/version /dependencygroupId是组织标识artifactId是模块名称version是版本号。这三个坐标唯一确定一个jar包。Maven拿到坐标之后去哪里找按顺序覆盖三个地方本地仓库、远程镜像仓库、中央仓库。本地仓库默认在用户目录下的.m2/repository所有下载过的依赖都会缓存到这里。远程仓库是你自己配置的镜像或公司私服。中央仓库是Maven官方服务器地址在国外直接访问速度不稳定——所以国内团队几乎都会配一个阿里云镜像。用生活化的方式理解中央仓库是远在国外的总店本地仓库是你家冰箱镜像仓库是楼下便利店。Maven找jar包先翻冰箱没有再去便利店便利店还没有才考虑跨国采购。这里有个新手最容易忽略的点IDEA里如果指定了本地仓库路径但这个路径和命令行默认路径不一致就会出现“IDEA里明明有依赖跑到命令行就全要重新下载”的现象。我建议所有地方都沿用同一个本地仓库目录别在IDEA里单独改来改去。1.2 生命周期mvn install到底执行了多少步执行mvn clean install时Maven并不是“先删掉target再打一个包”这么简单。它内部有一个固定的生命周期阶段序列默认都会依次执行阶段作用validate校验项目结构是否完整compile编译src/main/java下的源码test运行src/test/java下的单元测试package打成jar/war包verify运行集成测试并检查校验结果install把构建产物安装到本地仓库供其他项目引用注意直接执行package时test阶段也会跑因为package在test后面。如果只想打包跳过测试常用的命令是mvn clean package -DskipTests或者用-Dmaven.test.skiptrue连测试代码一起跳过编译。很多人在CI上构建不稳定多半就是单元测试里有环境依赖。每个阶段背后都有对应的Maven插件在干活——编译用的是maven-compiler-plugin打包用的是maven-surefire-plugin。这些插件本身也是从仓库下载的所以第一次执行构建会特别慢因为除了项目依赖Maven还要把一堆插件拉下来。1.3 settings.xml是全局配置中心Maven有两个层级的配置文件。全局配置在Maven安装目录下的conf/settings.xml用户配置在~/.m2/settings.xml。规则是用户配置覆盖全局配置。当你在IDEA里看到“User settings file”指向了Maven安装目录里的默认settings.xml那就说明你根本没用上自己写的镜像配置。所有关于仓库镜像、本地仓库路径、代理、私服认证等配置全部集中在settings.xml里。这篇文章后半部分讲的镜像配置和依赖报错几乎都是围绕这个文件展开的。建议先备份一份原始的settings.xml改坏了随时能还原。2. 下载安装与环境变量版本选错会让排查方向跑偏Maven的安装步骤看起来就是“解压配环境变量”但实际工作中有一半的依赖问题其实是因为版本和JDK不匹配引起的。版本选错后面排查一整天都找不到头绪。2.1 版本和JDK怎么搭配别随手拿最新版访问Maven官网下载页面时有几个主要分支3.6.x、3.8.x、3.9.x。不同版本对JDK的要求不一样建议按项目实际情况选择而不是永远拿最新版。Maven版本对应JDK典型使用场景Maven 3.6.3JDK 8老项目、企业存量项目最稳的组合Maven 3.8.xJDK 8/11Spring Boot 2.x项目的常见标配Maven 3.9.xJDK 8及以上新项目、Spring Boot 3.x推荐使用判断环境是否匹配先看JAVA_HOME指向哪个JDK版本再看Maven版本。如果JDK版本过新而Maven版本太老可能直接报“Unsupported major.minor version”反过来JDK太老而Maven太新也会因为Maven运行时需要高版本Java而启动失败。下载的时候注意选文件Windows用户下载apache-maven-x.x.x-bin.zipLinux/macOS用户下载apache-maven-x.x.x-bin.tar.gz。千万别下-src.zip那是源码包不是可运行的二进制发行版。2.2 环境变量MAVEN_HOME、PATH与JAVA_HOME的三角关系Maven本身是Java写的一个命令行工具运行时必须有JAVA_HOME环境变量。没有JAVA_HOME的话Maven启动脚本连Java虚拟机都找不到。所以安装顺序通常是先装JDK配置JAVA_HOME再解压Maven配置MAVEN_HOME。Windows下配置步骤新建系统环境变量MAVEN_HOME值为Maven解压目录比如D:\apache-maven-3.9.6。编辑系统变量Path新增%MAVEN_HOME%\bin。重新打开CMD窗口执行mvn -v验证。macOS和Linux下在~/.zshrc或~/.bashrc里加上export MAVEN_HOME/opt/apache-maven-3.9.6 export PATH$PATH:$MAVEN_HOME/bin然后执行source ~/.zshrc让配置生效。这里有个非常经典的坑Windows下改了环境变量后已经打开的命令行窗口不会自动刷新必须重新开一个。很多人在旧的CMD里敲mvn -v发现提示不是内部命令就以为配置失败其实只是窗口没重开。另外Path里不要手滑在%MAVEN_HOME%\bin末尾加多余的分号或空格这种隐藏字符会让命令找不到。2.3 老系统Windows 7和国产系统的安装特例“Maven有麒麟版吗”这个热搜词很有意思——Maven是纯Java程序本质上不区分操作系统和CPU架构只要目标机器上有对应版本的JDK解压就能跑。麒麟这类国产Linux系统上安装Maven流程和Linux完全一样装JDK、解压、设环境变量没有任何所谓“麒麟专用版”。Windows 7是个更容易踩坑的场景。老系统默认没有启用TLS 1.2而新版Maven在下载依赖时需要走HTTPS连接如果系统TLS版本支持不到位会一直报“Could not transfer artifact”或证书错误。我的建议是Windows 7机器优先使用Maven 3.6.3 JDK 8的组合同时让系统安装微软的TLS 1.2补丁。别尝试在Win7上强行跑最新版Maven浪费的时间远远超过它带来的好处。3. 镜像仓库配置阿里云之外的稳定方案配置镜像应该是整个Maven使用中性价比最高的一步。很多人从中央仓库下载依赖卡到怀疑人生配好镜像后从几分钟缩短到几十秒。但镜像配置也有不少细节配错了不是不生效就是私服依赖全被拦了。3.1 阿里云镜像标准配置先用最保险的方式跑通在~/.m2/settings.xml的mirrors标签下加这样一段mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror这段配置的作用把对中央仓库的访问全部重定向到阿里云的public仓库。public仓库聚合了中央仓库和JCenter的绝大多数依赖日常项目足够用了。配置完成后验证是否生效不要打开IDEA看先在命令行执行mvn help:effective-settings这个命令会输出最终生效的settings.xml内容。如果mirror段存在说明配置已经被读取。再用mvn dependency:resolve实际拉一次依赖观察输出里的下载地址是不是maven.aliyun.com。3.2 mirrorOf不只是一个仓库名几个取值到底在控制什么mirrorOf是最容易写错的地方。它的作用是声明“我要拦截哪些仓库请求”常用写法见下表写法含义适用场景central只拦中央仓库最安全适合配置了私服的项目*拦截所有仓库国内环境强加速但会拦截公司私服external:*拦截除localhost和file协议外的所有仓库兼顾私服本机部署repo1,repo2只拦指定id的仓库多镜像精确分流很多教程直接让你写*我建议谨慎。如果公司内部有Nexus私服写了*意味着所有私服请求也被抢到阿里云去了那项目里特有的内部依赖全部下载不了。更好的做法是用central或明确列出仓库id。另外多个mirror同时存在时Maven只会使用第一个匹配当前仓库的mirror后面的同类配置不会生效。这个特性导致“我配了五个镜像结果只有第一个起作用”的现象很普遍。3.3 多镜像配置的正确姿势当阿里云缺某个依赖想加华为云或腾讯云作为补充时正确的做法是让不同镜像负责不同仓库id而不是都写在mirror里。常见的多镜像配置mirrors mirror idaliyun-public/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror mirror idhuaweicloud/id mirrorOfspring-milestones/mirrorOf urlhttps://repo.huaweicloud.com/repository/maven//url /mirror /mirrors如果某个依赖连公共镜像都没有就需要在pom.xml里单独配置repository让它去指定的仓库查找。mirror和repository的区别在于mirror是“拦截并改写到统一地址”repository是在pom.xml里声明“额外去哪些仓库找”。两者不冲突但最好先用mirror统一入口再在pom.xml里加例外仓库。3.4 配了镜像还是不生效三个排查方向按我排查过的经验镜像“不生效”90%出在下面三个原因settings.xml文件位置不对。你改了Maven安装目录conf/settings.xml但IDEA实际使用的是~/.m2/settings.xml或者反过来命令行用的是用户settingsIDEA里却Override指到了旧文件。配置没在mirrors标签里。有人手滑把mirror写到了profiles或pluginRepositories里Maven直接忽略。仓库id和mirrorOf不匹配。下载失败的坐标来自某个仓库id比如nexus但mirrorOf只写了central自然不会拦那个仓库。检查时优先用mvn help:effective-settings看结果而不是反复猜“是不是IDEA缓存了”。IDEA确实有配置缓存但命令行不会骗人。4. IDE集成IDEA、Cursor、Trae里的Maven“抽风”现场用命令行跑通之后还要让Maven在IDE里顺滑工作。这一节的常见问题基本都来自热搜词idea配置maven、maven工具栏不见了、idea创建maven工程src目录不完整、cursor怎么配置java和maven。每个我都实际处理过。4.1 IDEA里三个必改配置别再让内置Maven跟你打架打开Settings → Build, Execution, Deployment → Build Tools → Maven重点看三块Maven home path这里默认可能是IDEA自带的Bundled (Maven 3)。我建议改成你自己安装的Maven目录。好处是命令行和IDE使用同一套Maven行为完全一致不会出现“命令行打包成功、IDEA里却报插件找不到”这种奇怪差异。User settings file勾选Override指向~/.m2/settings.xml。不勾选的话IDEA有可能读的是安装目录里的默认配置你配的阿里云镜像全部白搭。Local repository确认指向正确的本地仓库路径。如果你之前已经下载过不少依赖这个路径不能错推荐一律使用~/.m2/repository。改完配置后点IDEA右侧Maven工具窗口里的刷新按钮Reload All Maven Projects让依赖重新解析。很多人改完配置发现依赖还是标红就是忘了触发重新加载。4.2 Maven工具栏不见了去哪找Maven工具窗口消失最常见的原因是项目没有被正确识别为Maven工程而不是IDEA坏了。排查顺序看项目里有没有pom.xml文件。没有的话这个项目压根不是Maven项目需要在项目结构中Add Framework Support选择Maven才会自动生成pom.xml。如果pom.xml存在但IDEA没识别右键pom.xml选择Add as Maven Project工具窗口就会回来。从顶部菜单栏进入View → Tool Windows → Maven手动召唤。如果还是没有去Settings → Plugins搜索Maven相关插件确认没有被误禁用。还有一个比较坑的场景IDEA的Maven工具窗口里啥都有但双击某个依赖时没有下载动作状态一直显示“Downloading…”然后卡死。这种情况多半是网络请求走了错误代理去Settings → Appearance Behavior → System Settings → HTTP Proxy检查一下选No proxy或正确的自动检测确认之前没有手动填一个失效的代理地址。4.3 新建Maven工程src目录不完整用IDEA创建Maven工程时如果选了不用的骨架模板经常出现只有src目录但里面没有src/main/java、src/test/java这些标准目录的情况。这不是工程坏了而是maven-archetype生成的模板本来就不全。解决办法手动创建目录结构然后在src/main/java目录上右键选择Mark Directory as → Sources Root对src/test/java同样操作标记为Test Sources Root。图标会从黄色变成蓝色或绿色IDEA才真正把它们识别成源码目录。以后再新建只需创建一次这套结构会记录在.idea里。如果你希望IDEA默认把Maven相关配置固定下来可以在配置完Maven后在Settings窗口底部找Save as Default相关入口新项目就会继承当前设置。4.4 Cursor、Trae这类VS Code系工具的Maven配置很多人以为只有IDEA需要配Maven其实Cursor、Trae这类基于VS Code内核的编辑器也要配。它们没有IDEA那样直接的Maven工具窗口通常依赖扩展比如Maven for Java或vscode-maven。装好扩展之后在编辑器的settings.json里加上{ maven.executable.path: /opt/apache-maven-3.9.6/bin/mvn, maven.settings.file: /root/.m2/settings.xml }这两个配置分别指定Maven可执行文件和settings.xml位置。不指定的情况下扩展会自己找PATH里的mvn但经常因为PATH不确定导致找不到。Cursor这类编辑器还有个实际用法直接用它的终端跑Maven命令。报错信息比某些IDE的图形界面显示得更完整排查起来反而舒服。它内置的AI辅助还能根据终端输出直接给出下一步排查建议让“配置Maven”这件事门槛低了很多。5. 依赖报错从“download from maven failed”开始的完整排查链路依赖报错是Maven使用中最高频的痛点。热搜词里“intellij idea sqlserver jdbc 自动下载 download from maven failed”这种长尾需求本质就是依赖没拉下来。很多人一看到failed就开始百度其实正确的做法是沿着报错链路一层层定位。5.1 先看报错里的坐标和URL而不是急着改配置几乎所有下载失败都会在日志里告诉你具体坐标。比如Could not transfer artifact com.microsoft.sqlserver:mssql-jdbc:jar:9.4.1.jre8 from/to central (https://repo1.maven.org/maven2/): ...这里的mssql-jdbc:jar:9.4.1.jre8就是目标坐标repo1.maven.org是实际请求的仓库地址。这个URL本身是最重要的线索。把它复制到浏览器里访问如果浏览器都打不开说明网络层面有问题去检查代理和DNS如果浏览器秒开、命令行却失败那就是Maven侧的仓库配置问题。浏览器能访问但依赖下载失败常见原因就是镜像没生效或者镜像本身没同步这个文件。新版Maven在settings.xml里如果没有正确配置阿里云镜像请求会走去中央仓库下载速度慢大文件容易超时失败。所以排查第一步永远是确认实际请求地址是不是你预期中的镜像。5.2 本地仓库里成堆的.lastUpdated文件看不见的毒药在本地仓库的失败目录下经常会看到大量以.lastUpdated结尾的文件。这些是Maven在下载失败后留下的标记只要存在Maven在默认更新策略下会认为“这个版本刚下载失败过不必重试”于是你又反复触发下载它又反复跳过。处理方法很简单手动删掉这些标记文件。可以在仓库目录下执行find ~/.m2/repository -name *.lastUpdated -type f -delete也可以不删除直接在下载时加强制更新参数mvn clean install -U-U参数会让Maven强制检查并刷新快照和失败记录。但有时IDEA图形界面的Reload不会彻底清除标记命令行更靠谱。删除后重新执行依赖解析之前一直失败的依赖往往就能顺利拉下来。5.3 依赖标红与传递依赖冲突的处理顺序依赖标红不一定都是下载失败也可能是版本冲突或依赖传递问题。一个项目里A依赖B的1.0版C又依赖B的2.0版Maven会按“最近优先”原则选择一个版本如果选出来的版本和某个API不兼容编译就会报错IDEA里表现为某段代码标红。查询冲突用mvn dependency:tree输出里能看到某个依赖到底是从哪条链路引入的。要排除某条传递依赖在pom.xml里dependency groupIdcom.example/groupId artifactIdapp/artifactId version1.0/version exclusions exclusion groupIdcom.example/groupId artifactIdconflict-lib/artifactId /exclusion /exclusions /dependency要全局锁定版本用dependencyManagement项目还会统一管理所有子模块的依赖版本避免每个子pom各自为政。这个机制最适合多模块项目处理不同模块间的版本统一。5.4 zstd-jni这类带本地库的依赖为什么容易卡热搜词里有“maven仓库下载zstd”其实很多项目里是引入了com.github.luben:zstd-jni这个依赖。它里面包含各个平台的本地native库通过classifier区分不同操作系统版本导致下载的artifact数量多、体积大。如果当前镜像仓库没有缓存完整的文件列表下载时就容易超时失败。另外IDEA较新的版本在拉取部分依赖时会尝试协商zstd压缩传输日志里出现类似“Downloading via zstd”的字样不用慌这只是Maven客户端和服务端之间的传输协商失败后会退回普通压缩格式。关键还是要保证网络通畅并让本地仓库里残留的失败标记清除干净不要让它停在半成功状态。遇到这类大体积依赖如果怎么都下不全可以给IDEA的Runner增加更长的网络超时时间-Dmaven.wagon.http.connectionTimeout180000 -Dmaven.wagon.http.readTimeout180000放在Settings → Build, Execution, Deployment → Build Tools → Maven → Runner → VM Options里。这个方法也适用于其他大jar包反复下载超时的场景。6. 用命令行做最终验收mvn clean install一次通过配置了镜像、把IDE也理顺之后最后一步是用命令行做一次完整的构建验收。我自己的习惯是不管改了什么配置先跑一遍mvn clean install确认构建从零开始能通过再打开IDEA干别的。命令行通过的构建到IDEA里大概率没问题命令行失败的时候IDEA里再折腾也都是白费功夫。6.1 为什么优先用命令行而不是直接看IDEIDE的依赖解析是有缓存的有时候settings.xml改了半天IDE里的错误标记还留在界面上误导你继续排查实际上命令行已经构建成功了。命令行是Maven最原始、最直接的接口报错信息不像IDE有时会截断完整的堆栈和下载地址都会打出来。环境变量和settings.xml按最基础的方式生效能直接暴露你配置文件里的问题。跑一次干净构建等于验证了本地仓库、镜像、插件、生命周期所有环节。命令行的失败信息里最典型的几类直接对应不同环节报错关键词对应问题优先排查方向Could not transfer artifact网络或仓库配置镜像URL、代理、浏览器是否能访问Non-resolvable import POM父POM或依赖POM缺失检查坐标版本、私服配置Failed to execute goal org.apache.maven.plugins插件执行失败看具体插件、JDK版本、内存参数BUILD FAILURE测试失败单元测试未通过本地跑测试确认用例环境Unsupported major.minor versionJDK与Maven版本不匹配检查JAVA_HOME和Maven要求6.2 第一次完整构建会经历什么第一次执行mvn clean install时控制台会刷几分钟的下载日志。这是正常现象。Maven要下载的不是只有项目依赖还有大量构建插件比如clean插件、compiler插件、surefire插件、jar插件。这些插件默认也是从你配置的镜像拉取镜像越好初始构建越快。如果你配置了阿里云镜像下载速度通常可以接受。看到BUILD SUCCESS才算真正完成。有些人看到一段WARNING就以为失败了其实Maven的警告很常见比如“The POM for xxx is invalid”或“deprecation warning”这类警告只要没有[ERROR]都不影响产物生成。构建产物的位置在target/目录下install之后还会把jar包安装到本地仓库供同一个机器上的其他项目引用。6.3 几个值得长期坚持的经验这套流程跑熟了之后有几个经验我觉得比任何文档都实用。第一settings.xml一定要备份。我经历过一次手滑把localRepository写错路径结果Maven把依赖当成全新下载硬盘空间几乎被挤爆。现在我的~/.m2/settings.xml后面永远放一份settings.xml.bak。第二本地仓库别放C盘。Windows用户如果把默认的本地仓库留在用户目录一个跑了两年的项目依赖动不动就几个GB系统盘不够用的日子很难受。改localRepository路径到D盘或E盘一劳永逸。第三提交代码前跑一次命令行构建。IDE里编译通过不代表干净环境能构建成功。依赖冲突、插件缺失这种问题在命令行下暴露得最彻底。自己主动先撞见总比CI上撞见强。第四看到BUILD SUCCESS之后先别急着关终端。把输出往上翻看看有没有明显的WARNING顺手处理掉多余的废弃依赖提醒项目维护成本会越来越低。最后再分享一个小技巧说一个我最近常用的习惯不管在IDEA里点了多少次Reload遇到依赖相关的问题我都会先执行一遍mvn help:effective-settings再执行mvn dependency:resolve -U。两步加起来不到一分钟但能明确告诉我“Maven自己认为的最终配置是什么”和“依赖实际下载是否成功”。这比在IDE图形界面里反复猜测可靠得多。Maven这个工具没什么高深莫测的核心就是坐标、仓库、生命周期三个概念加上settings.xml一个配置文件。把环境变量和镜像配好再学会找出下载失败的URL绝大多数问题都能自己解决。剩下的就是多踩几次坑、多归纳几套命令下次遇到相同的报错看一眼输出就能定位到根因。
