直接说结论Maven 的安装配置本身不难难的是配完之后 IDEA 到底用的是不是你配的那套。我见过太多人跟着教程把mvn -v敲通了进 IDEA 一跑项目还是龟速下载依赖甚至编译报错找不到包最后发现 IDEA 里根本还在用自带的 Maven——这种问题十次有八次是配置入口没找对。这篇文章我就从 Maven 的职责讲起一路走到环境变量、settings.xml、IDEA 集成和报错排查把每一步的为什么也说清楚照着做基本不会再翻车。1. 先搞清楚Maven 在你的项目里到底干了什么活很多初学者把 Maven 当成一个下载依赖的工具这么理解没错但不够。Maven 是一个项目构建管理工具它管两件事一是项目依赖的下载与存储二是项目的编译、测试、打包、部署全流程。你可以把它想成一个包工头你要盖楼项目它帮你清点建材依赖 jar 包按图纸施工编译最后交付成品打包。1.1 依赖管理从手动找 jar 包到写个清单自动拉取没有 Maven 的年代Java 开发者是这样的用某个框架先去官网下载 jar 包或者从一个分享站下载别人打包好的 lib 目录然后手动 Copy 到项目的WEB-INF/lib下面再在 IDEA 里逐个 Add as Library。如果框架还依赖别的库你得自己顺着文档把传递依赖一个个找齐版本冲突更是噩梦——A 库需要 Log4j 1.xB 库需要 Log4j 2.x你只能二选一或者同包里塞两个迟早出事。Maven 改变的是这个流程你在pom.xml里写清楚我要用 Spring Web 这个依赖版本 5.3.20Maven 就去中央仓库一个全球的公共 jar 包仓库拉取这个依赖同时自动把它的传递依赖也一并拉回来。这个机制大大解放了人力也让依赖版本变得可声明、可追溯、可复现。1.2 构建生命周期一条命令完成编译到部署依赖只是 Maven 的一半能力另一半是构建。Maven 定义了一套标准生命周期核心阶段有这几个validate、compile、test、package、verify、install、deploy。你只需要敲一条命令mvn clean install它会先清理target目录然后编译源码跑单元测试打包成 jar/war最后安装到本地仓库供同机其他项目以依赖方式引用。整个过程是一串代执行的这也是为什么 Maven 项目比手动管理的项目可重复性高得多——换一台机器只要pom.xml和代码在一条命令就能造出一样的产物。1.3 本地仓库下载一次全家共享依赖不是每次构建都从网上下载的。Maven 会把下载过的 jar 包缓存在一个本地目录默认是用户主目录下的.m2/repository。这个目录里按groupId/artifactId/version三层目录结构存放 jar 包同一个依赖在一个版本下只会下载一次之后直接读本地缓存。这也是为什么配置本地仓库位置这么重要如果默认放在 C 盘项目多了之后随便就是几个 GBC 盘空间告急迁移路径就成了一等一的大事。理解了这个机制后面所有配置你都能对上号环境变量让系统能找到 Maven 程序settings.xml告诉 Maven 去哪里下载、缓存到哪里、用什么 JDK 编译IDEA 里的配置则决定这个 IDE 调用哪一个 Maven、读哪一份settings.xml。2. 安装之前必须确认的版本兼容性别等报错才回头安装 Maven 之前第一步不是下载而是确认你机器上的 JDK 版本。Maven 是 Java 写的它运行在 JVM 上所以 JDK 版本直接影响 Maven 能否运行以及构建产物支持的 Java 版本。2.1 先确认 JDK 装没装、版本是多少Windows 下打开 CMD 或 PowerShellmacOS/Linux 打开终端敲java -version正常情况下你会看到类似这样的输出java version 1.8.0_391 Java(TM) SE Runtime Environment (build 1.8.0_391-b13) Java HotSpot(TM) 64-Bit Server VM (build 25.391-b13, mixed mode)如果你装的是 JDK 17输出会类似openjdk version 17.0.9 2023-10-17 OpenJDK Runtime Environment (build 17.0.99) OpenJDK 64-Bit Server VM (build 17.0.99, mixed mode)如果提示java不是内部或外部命令说明 JDK 没装或者没配环境变量。Maven 不能单独工作它必须跑在 JDK 之上所以先把 JDK 装好再谈 Maven。2.2 Maven 版本与 JDK 版本的匹配关系Maven 每个大版本都有它支持的 JDK 最低版本装太老的 Maven 配太新的 JDK 或者反过来都可能出问题。下面这张表是实践中比较稳妥的搭配建议Maven 版本最低 JDK 版本推荐使用场景Maven 3.6.3JDK 1.7老项目维护、历史系统兼容Maven 3.8.8JDK 1.7大多数企业项目的稳妥选择Maven 3.9.xJDK 8新项目首选对 JDK 17/21 支持良好我个人的建议是如果你在用 JDK 8用 Maven 3.8.x 就好稳定且生态兼容好如果你已经切到 JDK 17 甚至 JDK 21直接上 Maven 3.9.x。有些新特性比如基于 Java 17 的模块化相关处理在老版本 Maven 上表现不如预期没必要给自己埋雷。2.3 下载源怎么选官网慢国内镜像站更快Maven 本体就是一个压缩包到哪儿下都行。Apache Maven 官网是最权威的但国内直连速度通常不理想。这里推荐几个国内镜像站点速度明显更快清华大学开源软件镜像站https://mirrors.tuna.tsinghua.edu.cn/apache/maven/阿里云镜像站https://mirrors.aliyun.com/apache/maven/华为云镜像站https://repo.huaweicloud.com/apache/maven/上面这些站点各自维护着 Apache 的同步目录你找到maven-3/目录选一个以bin.tar.gzmacOS/Linux或bin.zipWindows结尾的压缩包下载即可。注意不要下载src结尾的源码包那是源码需要自己编译我们用不着。提示下载时留意文件版本号比如apache-maven-3.9.6-bin.zip就是可直接使用的二进制发行包。3. 从下载到环境变量Windows 与 macOS/Linux 的完整安装路径3.1 Windows 下的解压与 MAVEN_HOME 配置Windows 下安装 Maven 不需要安装包解压即用。把下载好的apache-maven-3.9.6-bin.zip解压到你希望存放的位置比如D:\dev\apache-maven-3.9.6。这里注意路径里不要带中文和空格否则后面各种工具解析路径容易出幺蛾子。接下来配置环境变量步骤是这样右键此电脑 → 属性 → 高级系统设置 → 环境变量在系统变量区域点击新建变量名填MAVEN_HOME变量值填D:\dev\apache-maven-3.9.6在系统变量里找到Path双击打开新建一行填%MAVEN_HOME%\bin确定保存为什么不是直接配到Path里因为配了MAVEN_HOME之后以后升级 Maven 只需要改这一个变量的值Path里的%MAVEN_HOME%\bin会自动跟着变管理起来更清爽。这是一个很实用的小习惯。配置完需要重新打开一个 CMD 窗口新开的窗口才会加载新的环境变量然后验证mvn -v看到类似输出就说明安装成功Apache Maven 3.9.6 (bc2320e996a5c4f9d2f9a9b3d5b3e5a5c5e0e0) Maven home: D:\dev\apache-maven-3.9.6 Java version: 1.8.0_391, vendor: Oracle Corporation, runtime: ...3.2 macOS/Linux 下的解压与 profile 配置macOS 和 Linux 的安装思路一样把apache-maven-3.9.6-bin.tar.gz下载下来后解压到/usr/local/或你自己的工具目录tar -zxvf apache-maven-3.9.6-bin.tar.gz sudo mv apache-maven-3.9.6 /usr/local/然后编辑环境变量配置文件。macOS 上如果你用 zsh编辑~/.zshrc如果还在用 bash编辑~/.bash_profile或~/.bashrc。Linux 下通常是~/.bashrc。在文件末尾追加export MAVEN_HOME/usr/local/apache-maven-3.9.6 export PATH$MAVEN_HOME/bin:$PATH保存后让配置生效source ~/.zshrc然后同样验证mvn -v。3.3 环境变量的原理为什么配置了 bin 目录就能全局执行这里补一个基础知识点操作系统在终端里敲命令时会在PATH变量列出的所有目录里查找匹配的可执行文件。Maven 安装目录下的bin文件夹里有mvnLinux/macOS 用的 shell 脚本和mvn.cmdWindows 用的批处理脚本把bin目录加进PATH你在任何路径下敲mvn都能被找到。如果你碰到mvn -v能用但重启后失效这类情况多半是环境变量配到了临时会话级别的变量上或者 source 的配置文件不对。Windows 用户注意新开窗口才生效别在一个旧的 CMD 里反复试。4. 一把梭配置 settings.xml仓库位置、国内镜像、JDK 编译版本一次到位Maven 安装成功只是第一步真正决定好不好用的是settings.xml。这份配置管着本地仓库存哪、依赖从哪下载、项目按哪个 JDK 版本编译是 Maven 使用体验的分水岭。4.1 该改哪个 settings.xml全局配置与用户配置的取舍Maven 有两个settings.xml文件别搞混配置文件位置类型生效范围$MAVEN_HOME/conf/settings.xml全局配置该 Maven 安装下的所有用户~/.m2/settings.xml用户配置只对当前系统用户生效全局配置在 Maven 安装目录下用户配置在用户主目录下。我的建议是优先配置用户目录下的~/.m2/settings.xml原因有二第一升级 Maven 版本时全局配置可能被覆盖而用户配置独立保留第二不同用户可以用不同的镜像和仓库路径互不干扰。你可以先看看~/.m2目录存不存在这个文件如果没有不要从零手写直接去$MAVEN_HOME/conf/settings.xml复制一份过来再改避免漏掉必要标签结构。4.2 localRepository把仓库搬出 C 盘默认的本地仓库路径是~/.m2/repository。放在 C 盘的问题我在前面说过项目一旦多起来这个目录轻松膨胀到 3~5 GB全堆在系统盘。所以强烈建议把它换到一个单独的分区或目录比如D:\maven-repositoryWindows或/Users/你的用户名/maven-repositorymacOS。在settings.xml中找到localRepository这个标签默认是被注释掉的settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd !-- 本地仓库路径设置 -- localRepositoryD:\maven-repository/localRepository /settingsWindows 下路径里的反斜杠在 XML 里没问题但如果你有洁癖用正斜杠/也完全支持比如D:/maven-repository。配置完可以先手动执行一条命令让 Maven 把本地仓库目录建好mvn help:evaluate -Dexpressionsettings.localRepository -q -DforceStdout正常会输出你配置的路径。4.3 mirror 镜像配置解决下载慢到怀疑人生刚装好 Maven 直接建项目的话依赖默认从 Maven 中央仓库repo.maven.apache.org拉取国内直连速度通常比较慢下载几十 MB 的依赖等几分钟是常态。解决办法是配一个国内镜像。在settings.xml的mirrors标签里加如下配置mirrors mirror idaliyunmaven/id name阿里云公共仓库/name !-- 对所有仓库都使用该镜像 -- mirrorOf*/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrorsmirrorOf填*表示所有仓库请求都走这个镜像简单直接适合大多数人。如果有一些特殊的私有仓库不想走公共镜像那你需要配置更精细的匹配规则但这是进阶玩法这里不展开。另外提醒一下阿里云公共仓库的public聚合了 central、jcenter 等几个公共仓库源直接用它就行不需要额外再配多个 mirror。国内也有其他云厂商提供的镜像比如华为云https://repo.huaweicloud.com/repository/maven/腾讯云https://mirrors.cloud.tencent.com/nexus/repository/maven-public/选一个稳定的就行没必要配多个因为 Maven 会按顺序匹配第一个可用的。4.4 profile 配置 JDK 编译版本告别无效的源发行版Maven 默认编译时使用的 Java 版本可能和你项目的目标版本不一致尤其当你本机 JDK 是 17而项目要求以 1.8 语法编译时就容易报无效的源发行版: 17或错误: 不支持发行版本 8。这类报错的根源就是编译期使用的 JDK 版本和项目要求不匹配。合理的做法有两层第一层是在settings.xml的profiles标签里配置一个默认激活的 profile指定编译参数第二层是在项目的pom.xml里显式声明maven.compiler.source和maven.compiler.target。这里给出settings.xml层面的配置profiles profile idjdk-1.8/id activation !-- 默认激活 -- activeByDefaulttrue/activeByDefault /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如果你的项目使用 JDK 17把 source 和 target 改成都设成17。我的个人建议是尽量不要在全局写死一个版本更常见的做法是在pom.xml里按项目设置编译版本因为不同项目的目标版本可能不同。但全局配置适合那些所有项目都统一用某个版本的情况比如公司内部统一 JDK 8那就直接在settings.xml里配上省得每个pom.xml都写一遍。5. IDEA 里让本地 Maven 真正生效的三个配置入口到了这一步你的 Maven 已经能在命令行正常工作了接下来要让 IDEA 用它、用对。很多人栽在这一步——命令行配好了IDEA 里却在用自带的 Maven或者读了另一份settings.xml。5.1 打开设置面板的正确位置IDEA 的 Maven 设置藏得不算深但新老版本菜单名称略有差异。基本上路径是这样菜单栏 File → SettingsWindows或 IntelliJ IDEA → PreferencesmacOS展开左侧的 Build, Execution, Deployment → Build Tools → Maven这里就是 IDE 对 Maven 的所有核心配置入口。注意IDEA 2021 之前的版本有些选项叫法不同但大结构一致不至于找不到。5.2 Maven home path、User settings file、Local repository 三项联动配置进入 Maven 设置页后你会看到三项关键配置配置项作用建议值Maven home path指定使用哪个 Maven你解压的 Maven 目录如D:\dev\apache-maven-3.9.6User settings file指定读取哪个 settings.xml~/.m2/settings.xml你配置的那个Local repository指定本地仓库路径和 settings.xml 中 localRepository 保持一致这里有个非常关键的细节User settings file 这一项IDEA 默认会勾选 Override并且默认指向 IDEA 安装目录下的plugins/maven/lib/maven3/conf/settings.xml。如果你不手动改成自己的~/.m2/settings.xmlIDEA 就不会读取你配置的镜像和本地仓库路径哪怕 Maven home path 改对了也没用——下载依赖照样直连中央仓库慢得你想砸电脑本地仓库也还是默认的C:\Users\xxx\.m2\repository。正确做法是点击 User settings file 右侧的文件夹图标选择C:\Users\你的用户名\.m2\settings.xmlmacOS 是/Users/你的用户名/.m2/settings.xmlIDEA 会自动识别Local repository 会跟着自动显示为同一个配置路径。不需要手动改 Local repository让它从 settings.xml 同步读取即可这样以后在命令行和 IDEA 里用的是同一套仓库不会有命令行能看到依赖、IDEA 里却找不到包的割裂感。5.3 Runner 的 VM Options 与创建新项目慢的解法再往下翻Maven 设置页里有个 Runner 子页其中 VM Options 这个输入框经常被忽略但实际使用中非常关键。默认情况下用 IDEA 的 Maven 功能创建项目时它需要联网下载archetype模板比如maven-archetype-quickstart而这一步经常卡住很久看起来像是 IDEA 假死了。其实问题出在 archetype 插件每次都会尝试从中央仓库拉取最新的archetype-catalog.xml这个文件有几 MB下载慢就会卡那。解决方法是给 Runner 的 VM Options 加一行参数-DarchetypeCataloginternal含义是让 Maven 使用本地内置的 archetype 目录不要联网拉取那份大 catalog。加了之后创建 Maven 项目的速度会明显提升。另外还有一个更容易忽略的入口IDEA 的 Maven 设置在当前项目和新项目之间是隔离的。你这次改好了下次新建项目打开可能又变回默认。所以设置完当前项目后一定要再去File → New Projects Settings → Settings for New Projects里把同样的配置做一遍这样以后新建的每个项目都会继承这套 Maven 配置不用每次折腾。6. 配置完照样报错这是我整理的排查顺序与踩坑清单说到配完了还是报错这大概是 Maven 相关话题里最常见的求助帖来源了。很多报错表面复杂根因翻来覆去就那么几个。我这里给出一套实用的排查顺序和踩坑清单按链路走就能省掉大半折腾时间。6.1 从环境变量开始排查mvn -v 就报错时怎么查如果终端输入mvn -v直接提示不是内部或外部命令或command not found排查链路是这样确认MAVEN_HOME和PATH是否配置正确。Windows 下在 CMD 里输入echo %MAVEN_HOME%看看有没有输出路径如果没有回到环境变量面板检查是否写错变量名或路径。确认%MAVEN_HOME%\bin下真的有mvn.cmd。有时候安装包下载不完整或者解压目录选错bin 目录可能不存在。确认你新开的终端窗口确实重新加载了环境变量。Windows 下如果在一个旧的 CMD 窗口里反复试它永远是用旧环境变量启动的务必关掉重开。Windows 还有一个坑如果你配置了M2_HOME和MAVEN_HOME两个变量且指向不同路径某些工具会读取M2_HOME导致实际生效的不是你想要的 Maven。建议统一只用一个现在官方主推MAVEN_HOME。6.2 IDEA 不认配置的排查链路如果你的命令行的mvn -v一切正常但 IDEA 里表现诡异比如依赖下载源还是慢、本地仓库还是默认 C 盘按这个顺序检查打开 IDEA 的 Maven 设置页确认 Maven home path 指向了你自己解压的目录而不是 IDEA 自带的。看 User settings file 是否勾选了 Override且路径指向你配置过的~/.m2/settings.xml。这是最容易被忽略的选项我见过太多人了前面全对就挂在 Override 上。看 Local repository 显示的路径是否和settings.xml里的localRepository一致。如果不一致说明 IDEA 没有真正读取你的settings.xml回头检查第 2 步。改完配置后右侧的 Maven 工具窗口里点一下刷新按钮或者叫 Reimport让 IDEA 重新解析导入配置。有时候 IDEA 的缓存不会立刻生效可以顺手 File → Invalidate Caches 清一下再重新打开项目。6.3 依赖下载失败的排查链路依赖下载报错常见的表现有Could not transfer artifact、PKIX path building failed、Connection timed out。排查顺序如下先确认是不是网络问题。直接访问你配置的镜像地址看看能不能正常打开。比如阿里云公共仓库的 URL在浏览器里能打开说明网络通路正常。检查settings.xml的 mirror 配置语法是否正确。mirrorOf写没写url末尾有没有多空格XML 标签有没有闭合。一个常见的错误是把mirror写进了profiles里或者漏了mirrors的包裹层Maven 会静默忽略而不是报错结果就是你完全没走到镜像。检查本地仓库目录的写入权限。Windows 下如果目录被其他进程占用或者 macOS 下权限不足Maven 可能无法写入本地仓库缓存也会报传输失败。终端执行mvn help:evaluate -Dexpressionsettings.localRepository -q -DforceStdout看看路径是否正确、可写。如果你的项目pom.xml里配置的仓库地址是一个已经失效的内网地址或私有仓库而settings.xml的mirrorOf又没有覆盖它请求会直接打到那个失效地址上超时是必然的。这种时候要么把项目和仓库地址对齐要么把mirrorOf改成*让所有请求都走公共镜像。6.4 编译版本报错的排查链路无效的源发行版和不支持发行版本这俩错误基本都指向 Java 版本不匹配排查链路如下终端执行java -version确认本机 JDK 版本。看项目的pom.xml里maven.compiler.source和maven.compiler.target写的什么版本两个值必须一致且不能高于 JDK 实际版本。如果你在settings.xml的 profile 里写死了编译版本而项目pom.xml又指定了另一个版本规则是pom.xml内的配置优先级更高但如果不一致也会造成奇怪的行为所以两边最好统一规划。一个隐藏坑IDEA 里 Project Structure 的 Project SDK 设置比如 Project SDK 选的 17和 Modules 里的 Language level比如设成 1.8如果不一致也可能在编译阶段触发类似的报错。这不在 Maven 范畴但既然是打包报错顺手查一下没有坏处。6.5 附一份配置速查表症状根因解决方案mvn -v找不到命令环境变量未配或未生效检查 MAVEN_HOME 与 PATH重开终端IDEA 依赖下载慢IDEA 未读取用户 settings.xml勾选 Override 并指向 ~/.m2/settings.xml本地仓库还在 C 盘settings.xml 未生效修改 localRepository 并让 IDEA 重新读取依赖传输失败/超时镜像未配置或配置错误添加 mirror 标签访问镜像检查网络无效的源发行版JDK 版本与编译目标不匹配统一 pom.xml 与 JDK 版本或配置 profile新建项目创建卡顿archetype 远程拉取慢Runner VM Options 加-DarchetypeCataloginternal我自己在实际配置环境的过程中最大的一个体会是Maven 的配置链条不长但每一环都讲究哪个配置源生效。命令行走一套配置IDEA 又走一套配置两套不一致才是各种诡异问题的根源。所以不要嫌麻烦装完之后花两分钟把settings.xml里localRepository和镜像配置逐项对一遍再把 IDEA 的两处入口都检查一次一劳永逸。最后再分享一个小技巧配置完成后你可以用mvn dependency:tree随便在一个项目里跑一下看看输出的依赖树是否和pom.xml预期一致。如果依赖树正常铺开说明 Maven 的拉取、解析、缓存链路是通的这时候再回 IDEA 里敲代码底气就足多了。