1. 先搞清楚Maven是什么再动手装也不迟在开始下载安装包之前我建议你先花三分钟弄明白Maven到底是干嘛的。因为我在实际带人过程中发现很多人照着教程装完之后配置也配了环境变量也加了但遇到依赖报错、构建失败时完全不知道从哪里下手。这不是操作问题是脑子里没有Maven的模型。Maven的本质是两件事第一是依赖管理第二是构建管理。依赖管理解决的是项目需要哪些jar包、从哪拿、版本怎么统一构建管理解决的是从源码到最终产物中间那些步骤什么时候编译、什么时候打包、什么时候跑测试。打个比方。以前不用Maven的时候你要去网上挨个找jar包下载然后拷到项目的lib目录里就像去旧货市场淘零件找得到找不到全看缘分。Maven相当于给你一份标准的快递清单你只要写上商品编号groupId、artifactId、version它自动帮你从仓库取货把你家门口货架本地仓库和电商大仓远程仓库都管起来。这套机制一旦理解后面所有配置你都看得懂。这一节内容适合两类人一是刚入行Java开发、以前只会用Eclipse手动导包的初学者二是已经装了Maven但一直稀里糊涂地能用就行的同学。搞清楚下面几个核心概念比会敲几个命令重要得多。1.1 Maven项目里最常听到的几个黑话POM文件是Maven的心脏。每个Maven项目根目录下都有一个pom.xml里面写的是这个项目的坐标、依赖列表、构建配置。坐标就是groupId、artifactId、version这三个组合用来唯一定位一个构件。我习惯管它叫快递地址三样缺一个都找不到货。依赖scope也是个高频概念。最常见的是compile、test、provided、runtime。不细说每个的官方定义你就记一个场景junit在写测试时用打包时不需要带上去所以scope是test。servlet-api在编译时需要但Tomcat里已经有了不能重复打进去所以用provided。搞懂这个后面处理依赖冲突时能少掉不少头发。生命周期则是Maven里最容易被忽略又最有用的设计。它的构建过程不像shell脚本那样执行完一条再执行下一条而是按阶段划分validate、compile、test、package、verify、install、deploy。你执行mvn install它不会只执行install这一步而是把install之前的所有阶段都依次执行一遍。这个机制后面我会在命令行实操那节展开讲。2. 版本选择和下载这一步偷懒后面全是坑网上搜Maven安装教程标题基本都在说下载安装包、解压、配环境变量但我踩过太多版本的坑所以单独开一节讲版本问题。Maven现在的版本线主要分三拨3.6.x系列、3.8.x系列、3.9.x系列另外还有个4.x正在往前推。很多老项目里写着3.6.3不是因为3.6.3功能多好而是当时公司搭环境用的就是这个版本大家就一直沿用。3.6.3本身也够稳定但如果你要新装我建议直接选3.9.x它兼容Java 8到Java 21日常开发完全够用。为什么不建议用最新的4.x不是它不好而是生态还没完全跟上。很多公司的私服、插件、父子工程配置都是在3.x上验证过的你本地用4.x跑偶尔会遇到插件兼容问题。做开发环境稳定优先别追求版本号新鲜。还有一件更要紧的事先确认你机器上的JDK版本。Maven本身跟你的项目编译是两回事但Maven运行需要JAVA_HOME指向一个可用的JDK。Maven 3.9要求JDK 8起步如果公司项目是JDK 17甚至JDK 21一样能用。真正要注意的是你不要装一个Maven 3.9然后配一个JDK 7环境变量那样mvn命令能执行但构建时会直接报Unsupported major.minor version。2.1 下载入口和国内加速源别再去官网死磕Apache官网的Maven下载页面是Maven的主阵地页面里会给两个选项Source的tar.gz和Binary的zip/tar.gz。我们要的是Binary别手滑下成Source那只是源码进去没有bin目录。问题在于官网服务器在国外直接下3.9.x的zip包经常龟速。我自己的经验是优先用清华大学开源软件镜像站或者阿里云镜像站地址分别是清华https://mirrors.tuna.tsinghua.edu.cn/apache/maven/maven-3/阿里https://mirrors.aliyun.com/apache/maven/maven-3/进去选对应的版本号目录找到apache-maven-3.9.x-bin.zip下载。如果网站封了国外下载地址镜像站几乎是唯一靠谱的选择。下载完之后最好对着官网页面上的SHA-512校验值核对一下文件我在本地遇到过下载的zip包是坏的解压到一半报错校验一遍能避免这种乌龙。3. Windows下安装Maven与环境变量配置的完整套路下载好zip包之后就是大家最熟悉的解压、配环境变量环节但这里面细节非常多。我见过很多新人在这一步卡住不是不会操作而是操作完发现mvn命令就是不能用。先讲目录选择。解压位置我建议放一个专门的开发工具目录比如D:\dev\maven\apache-maven-3.9.x不要直接放C盘里的用户目录也不要放带中文和空格的路径。中文路径在部分旧版插件里会出编码和解析问题空格路径在批处理脚本里也要小心引号匹配。还有一点尽量不要装在C:\Program Files这类目录因为普通用户权限在写日志和改配置时容易被系统拦住后面调用时你可能会被各种Access Denied折腾。3.1 环境变量一步一步配MAVEN_HOME、PATH、JAVA_HOME打开此电脑 → 属性 → 高级系统设置 → 环境变量在这个面板里我们要配两个东西。第一个是新建一个系统变量变量名MAVEN_HOME变量值填你的解压路径也就是到能看到bin目录的那个上层目录例如D:\dev\maven\apache-maven-3.9.x。不要手滑把路径填到bin这一层否则后面%MAVEN_HOME%\bin会变成D:...\bin\bin。第二个是编辑Path变量在变量值末尾加上%MAVEN_HOME%\bin。如果你之前装过其他版本的Maven或者装过某些IDE把Maven路径写进Path里了这里一定要检查一下重复的Maven路径会导致mvn -v出来的是旧版本。Path列表里配置越多越容易互相干扰我通常会精简到只留一个Maven路径。还有一个必备的JAVA_HOME变量。如果机器上已经装了JDK大概率有这个变量变量值指向JDK的安装目录比如D:\dev\jdk\jdk-17不包含bin。Maven的启动脚本靠JAVA_HOME去定位Java找不到JDK的话mvn命令会直接提示JAVA_HOME is not defined correctly。3.2 验证安装mvn -v这一行输出信息怎么读懂配置完环境变量一定要新开一个CMD窗口再执行验证命令因为CMD里的环境变量是在启动时读取的老窗口不会自动刷新。执行mvn -v正常会看到类似下面这样的输出Apache Maven 3.9.9 (8e2a2e6c...) Maven home: D:\dev\maven\apache-maven-3.9.x Java version: 17.0.11, vendor: Oracle Corporation, runtime: D:\dev\jdk\jdk-17 Default locale: zh_CN, platform encoding: UTF-8 OS name: windows 10, version: 10.0, arch: amd64这里要重点看两行Maven home是不是指向你自己的安装目录Java version是不是你预期的JDK版本。如果Maven home显示的路径不对说明Path里还有别的Maven在抢位置如果Java version不对多半是JAVA_HOME配到了别的JDK。如果你用的是macOS配置思路完全一样只是环境变量文件从系统设置换成了~/.bash_profile或~/.zshrc用brew install maven装也行路径稍有不同但settings.xml和本地仓库的配置逻辑跟Windows是一致的。4. settings.xml配置实战本地仓库、镜像仓库、JDK级别一次搞定环境变量配完Maven已经能跑了但离用起来顺手还差最关键的一步——settings.xml配置。这一步是Maven安装配置里最核心、也是网上教程最常被一笔带过的部分。settings.xml在哪个目录决定它的作用范围。Maven安装目录下conf/settings.xml是全局配置影响这台机器上所有用户用户目录下的~/.m2/settings.xml是用户配置只影响当前用户。实际开发中我建议配置在用户目录原因很简单你升级Maven版本时全局配置会被覆盖用户目录下的不会被影响而且IDEA默认读取的也是用户目录下的配置。4.1 第一件事改本地仓库路径Maven默认的本地仓库在C:\Users\你的用户名.m2\repository随着项目越建越多这个目录能膨胀到好几个G。我强烈建议把它挪出C盘放到一个独立的目录比如D:\dev\maven\repository。对应配置是在settings.xml里找到localRepository标签默认是被注释掉的把它打开并填路径即可localRepositoryD:\dev\maven\repository/localRepository改这个路径有两个实际好处一是C盘空间不会被jar包蚕食二是重装系统后D盘仓库还在重新配一次Maven不依赖也能直接跑旧项目省下大量重新下依赖的时间。如果团队有统一规范这个路径通常也会按公司要求固定方便配合CI机的构建缓存。4.2 阿里云镜像仓库配置以及多镜像怎么叠加下载依赖慢是国内Maven用户最痛的槽点。默认的中央仓库服务器在国外拉一个十几个依赖的小项目都能等半天。解决办法就是配镜像仓库。我用最多的是阿里云Maven仓库在settings.xml里的mirrors节点添加如下配置mirror idalimaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror这里mirrorOf写的是central意思是只拦截中央仓库的请求。很多人图省事会写成*表示所有仓库都走这个镜像。我不建议这么干因为公司如果有私有仓库Nexus或者项目里配置了特殊仓库把所有请求都劫持走轻则下载失败重则把私服上的内部构件路径搞乱。如果你还想再叠加一个备用镜像比如腾讯云或者华为云的仓库要注意mirror不是合并关系而是按顺序匹配Maven会使用第一个匹配当前仓库的mirror。所以可以按优先级排好mirrors mirror idalimaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror mirror idtencent/id nametencent maven/name urlhttps://mirrors.cloud.tencent.com/nexus/repository/maven-public//url mirrorOfcentral/mirrorOf /mirror /mirrors还有一点要专门提醒现在Maven新版本对HTTP协议仓库有限制3.8.1之后的版本如果你把镜像地址写成http://开头会直接提示镜像被阻断报错里带Blocked mirror字样。镜像地址一律用https避免踩这个暗坑。配置文件改完可以用mvn help:effective-settings这个命令查看最终生效的配置里面会把全局和用户级settings合并后的结果打印出来。第一次跑这个命令会下载插件等一会儿是正常的。4.3 用一个profile固定JDK编译级别Java项目最常见的编译级别不对问题表现是代码在本机跑得好好的同事拉过去打包就报invalid target release或source option 7 is no longer supported。这个问题的根源在于Maven默认的编译级别跟你本机JDK不匹配。你可以在settings.xml里加一个激活的profile让所有项目默认使用JDK 17或你需要的级别profiles profile idjdk-17/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target /properties /profile /profiles加了这段配置所有从这台机器构建的Maven项目默认都按Java 17编译不需要在每个项目的pom里反复声明。当然如果某个项目本身在pom里指定了不同的版本项目内的配置优先级更高不会冲突。4.4 配置好之后再确认一遍配置好settings.xml之后建议先跑两条命令验证不要直接打开IDEA导项目。第一条是mvn help:system它会显示当前使用的工作目录、本地仓库路径、系统属性和JDK信息。第二条是mvn help:effective-settings看镜像、本地仓库、profile有没有按预期生效。我在教别人配Maven时总强调一个习惯把settings.xml当成项目配置来管理。改动任何一个节点前先复制一份备份因为配置错误不会报语法错误而是会在某次构建时给你一个莫名其妙的依赖下载异常到时候排查起来特别费劲。5. 在IDEA里把Maven设置调明白一处配置处处顺畅命令行里的Maven配好了接下来就是IDE。很多人觉得IDEA能自动识别Maven不需要额外配置其实那是IDEA用自己的内置Maven在工作。版本可能有差异settings.xml也不会读你改过的用户配置最后出现命令行能打包IDEA里依赖全爆红的诡异现象。所以我到了新机器配置完命令行的第一件事就是打开IDEA进入Settings → Build, Execution, Deployment → Build Tools → Maven把三个地方改好。5.1 三个关键设置Maven home、User settings file、Local repositoryMaven home path那里选择你解压的Maven目录而不是用Bundled默认项。选好之后User settings file这一栏要勾选Override然后填上~/.m2/settings.xml的路径。这时候Local repository一栏会自动跟着settings.xml里的localRepository更新如果没有自动更新手动点一下刷新按钮。这三个设置的含义分别是让IDEA用哪个Maven程序、读哪份用户配置、依赖jar包下载到哪里。三者统一之后IDEA里的构建结果和命令行不会有偏差。5.2 搭配Runner配置让默认命令和模板加速在同一个Maven设置页面往下拉还有Runner区域这里面的VM Options和Properties很多人不注意。我建议在VM Options里加上一行-DarchetypeCataloginternal它的作用是新建项目时Spring Initializr或Maven骨架不再从网上远程拉取模板列表直接用本地缓存避免新建项目卡在Downloading archetype-catalog.xml这个步骤半天。另外如果IDEA里构建大项目频繁OOM可以在VM Options里加-Xmx1024m甚至更大。maven打包本身是独立进程但IDE内部索引和构建工具也吃内存适当调大能减少很多莫名报错。5.3 导入项目后依赖爆红先别删重装遇到IDEA导入Maven项目后依赖全部标红最常见的三个原因按概率排序第一是IDEA没有用你配置的settings.xml还在用内置Maven连中央仓库下载慢甚至会超时第二是本地仓库里有上次中断下载留下的.lastUpdated文件这种文件会让Maven误以为依赖不存在第三是JDK版本和项目要求的版本不一致。第三个问题尤其容易骗到新手。你看到一个报错说cannot resolve symbol但项目结构里其他文件都正常这时候先看Project Structure里Project SDK是多少。我自己帮人排查了十几次这类问题十有七八是project SDK没切到项目要的JDK版本。6. 命令行实操从clean install到依赖树排查把命令用到点子上配置再熟不会用命令行就等于只学了一半。因为公司的CI/CD脚本、运维同事的打包命令、以及你自己排查问题时绝大多数场景还是在终端里跑Maven。6.1 clean install到底干了些什么mvn clean install是出现频率最高的命令甚至已经成了很多团队的肌肉记忆。拆开来看clean是独立生命周期负责删除target目录install属于默认生命周期它会按阶段顺序执行validate、compile、test、package、verify、install最终把构建产物安装到本地仓库。所以mvn install不只是一个安装操作它把编译、测试、打包全部走了一遍再install到本地仓库。team里两个人做模块依赖开发时A模块改动后执行mvn clean installB模块才能拿到A的最新版本。中途跳过测试的写法是-DskipTests注意它只是跳过测试执行照样编译测试代码。如果想连测试代码编译都跳过用-Dmaven.test.skiptrue。实际交付时一般用后者更省时间但本地开发我建议还是跑一下测试提前暴露问题。6.2 常用命令组合速查这里我整理了一份给自己团队新人用的命令速查表覆盖最常见的场景。使用场景命令只编译不打包mvn compile编译并运行测试mvn test打包jar/war不跑测试mvn clean package -DskipTests安装到本地仓库供其他模块引用mvn clean install -DskipTests跳过测试代码的编译mvn clean install -Dmaven.test.skiptrue只构建指定模块mvn clean install -pl 模块名 -am查看依赖树mvn dependency:tree -Dverbose分析无用依赖mvn dependency:analyze其中-pl和-am这对参数在多模块工程里非常实用。-pl指定要构建的模块-am表示同时构建它的依赖模块。只改了其中一个子模块时用这两个参数能把构建时间从分钟级压到几十秒。6.3 依赖冲突排查NoSuchMethodError的元凶很多人被依赖冲突折磨过代码本地能过一到服务器上就抛NoSuchMethodError或者ClassNotFoundException。这通常不是代码问题而是同一个类被两个不同版本的jar包打包了JVM按classpath顺序加载了旧版的那个。排查的第一步就是看依赖树。执行mvn dependency:tree -Dverbose输出会列出所有依赖和它们的传递依赖。看到同一groupId和artifactId出现两次但version不同基本就能锁定冲突点。解决方式有几种在pom里对多余的传递依赖加exclusion或者直接升级引发冲突的依赖到统一版本。这里要提醒一下千万别图省事把所有传递依赖都exclusion掉那样很可能另外一个功能就悄悄挂了。改一个跑一次测试稳扎稳打。7. 常见问题排查实录Maven安装与配置里最容易踩的10个坑配置Maven这件事本身不难难的是报错信息五花八门。我在日常支持同事的过程中积累了一些高频问题写成速查表放在这里碰到对号入座就行。报错/现象排查方向mvn不是内部或外部命令环境变量Path没配好或新开CMD了吗mvn -v显示的是旧版本Path里有多个Maven路径保留一个JAVA_HOME is not defined correctlyJAVA_HOME指向了JRE或路径带bin下载依赖特别慢镜像仓库还没配或mirrorOf写错中央仓库的jar包无法下载镜像地址用了http新版本Maven会阻断IDEA里依赖标红检查IDEA的Maven配置是否指向你的settings.xml项目编译版本不对检查profile里的maven.compiler.source/target某个jar包明明在本地仓库却一直读不到删除对应目录下的.lastUpdated文件再重新构建中文日志乱码Maven的platform encoding显示UTF-8但CMD控制台代码页是GBK改chcp 65001构建时权限不足Maven解压或仓库目录被放在需要管理员权限的位置7.1 一个经常被问到的需求两个本地仓库怎么合并我经常被问到我电脑上装了新旧两个版本的Maven形成两个repository目录想合并成一个有什么好办法Maven只支持一个localRepository所以合并不是配置层面的事情本质上就是文件系统的合并。repository目录的结构是groupId/artifactId/version/jar文件两个仓库结构一致的话直接把整个repository文件夹拷到一个目录里即可。如果你担心同名jar版本覆盖就用新一点的版本优先Maven构建时会按pom声明的版本去取不会因为你仓库里多几个版本而出问题。不过还有一种更干净的做法把仓库里那些本地安装的jar抽出来看有没有对应的pom文件如果没有用mvn install:install-file命令把它们重新安装到统一仓库里。这个做法适合那种同事发我了一个内部依赖让我安装到本地的场景命令如下mvn install:install-file -Dfilexxx.jar -DgroupIdcom.company -DartifactIdxxx -Dversion1.0 -Dpackagingjar如果你两个仓库里同一坐标有两个不同版本还是建议先确认当前项目和哪个版本匹配再决定保留哪个。无脑合并虽然大多数时候没事但版本冲突会以非常隐蔽的方式跑出来咬你。7.2 配置排查通用思路每次配完环境出问题我基本按这个顺序排查先mvn -v确认当前生效版本再mvn help:system确认本地仓库路径再mvn help:effective-settings看配置是否被合并最后才打开IDE看它有没有复用命令行配置。这四步走完90%的问题都能水落石出。还有个小技巧IDEA里改完settings.xml没生效时不用重启IDEA在Maven工具窗口点一下刷新按钮或者跑一次mvn help:effective-settings让配置重新加载。写在最后我装Maven这么多年的一点个人习惯装Maven本身不难但Maven环境的维护是一种长期投资。我一般在新机器上做完安装配置后会花五分钟跑一个新项目模板把整个构建流程走通确认没有报警再开始干活。这么做的好处是你能清楚区分我的环境有问题和项目本身有问题省去很多后面排查的时间。另外我始终坚持用一套配置管理所有环境同一份settings.xml、同一个本地仓库、同一个Maven版本。不管是命令行、IDEA还是后面接触到的VSCode它的Java插件也支持在设置里指定maven.settings路径都指向同一套文件。这样配置一次基本就不会再产生在IDEA里能跑终端里却报错这种割裂问题。最后再分享一个让我受益很大的小习惯每次准备调整settings.xml前先复制一份带了日期的备份文件放旁边。Maven配置不像代码有版本管理你很难立刻知道哪次改动引入的问题有个备份就能迅速回滚。别小看这一招关键时刻能救命。 
长河君 · 2026/10/9 10:43:45 · 阅读 1.2k Maven安装与配置完全指南：从环境变量到settings.xml实战
1. 先搞清楚Maven是什么再动手装也不迟在开始下载安装包之前我建议你先花三分钟弄明白Maven到底是干嘛的。因为我在实际带人过程中发现很多人照着教程装完之后配置也配了环境变量也加了但遇到依赖报错、构建失败时完全不知道从哪里下手。这不是操作问题是脑子里没有Maven的模型。Maven的本质是两件事第一是依赖管理第二是构建管理。依赖管理解决的是项目需要哪些jar包、从哪拿、版本怎么统一构建管理解决的是从源码到最终产物中间那些步骤什么时候编译、什么时候打包、什么时候跑测试。打个比方。以前不用Maven的时候你要去网上挨个找jar包下载然后拷到项目的lib目录里就像去旧货市场淘零件找得到找不到全看缘分。Maven相当于给你一份标准的快递清单你只要写上商品编号groupId、artifactId、version它自动帮你从仓库取货把你家门口货架本地仓库和电商大仓远程仓库都管起来。这套机制一旦理解后面所有配置你都看得懂。这一节内容适合两类人一是刚入行Java开发、以前只会用Eclipse手动导包的初学者二是已经装了Maven但一直稀里糊涂地能用就行的同学。搞清楚下面几个核心概念比会敲几个命令重要得多。1.1 Maven项目里最常听到的几个黑话POM文件是Maven的心脏。每个Maven项目根目录下都有一个pom.xml里面写的是这个项目的坐标、依赖列表、构建配置。坐标就是groupId、artifactId、version这三个组合用来唯一定位一个构件。我习惯管它叫快递地址三样缺一个都找不到货。依赖scope也是个高频概念。最常见的是compile、test、provided、runtime。不细说每个的官方定义你就记一个场景junit在写测试时用打包时不需要带上去所以scope是test。servlet-api在编译时需要但Tomcat里已经有了不能重复打进去所以用provided。搞懂这个后面处理依赖冲突时能少掉不少头发。生命周期则是Maven里最容易被忽略又最有用的设计。它的构建过程不像shell脚本那样执行完一条再执行下一条而是按阶段划分validate、compile、test、package、verify、install、deploy。你执行mvn install它不会只执行install这一步而是把install之前的所有阶段都依次执行一遍。这个机制后面我会在命令行实操那节展开讲。2. 版本选择和下载这一步偷懒后面全是坑网上搜Maven安装教程标题基本都在说下载安装包、解压、配环境变量但我踩过太多版本的坑所以单独开一节讲版本问题。Maven现在的版本线主要分三拨3.6.x系列、3.8.x系列、3.9.x系列另外还有个4.x正在往前推。很多老项目里写着3.6.3不是因为3.6.3功能多好而是当时公司搭环境用的就是这个版本大家就一直沿用。3.6.3本身也够稳定但如果你要新装我建议直接选3.9.x它兼容Java 8到Java 21日常开发完全够用。为什么不建议用最新的4.x不是它不好而是生态还没完全跟上。很多公司的私服、插件、父子工程配置都是在3.x上验证过的你本地用4.x跑偶尔会遇到插件兼容问题。做开发环境稳定优先别追求版本号新鲜。还有一件更要紧的事先确认你机器上的JDK版本。Maven本身跟你的项目编译是两回事但Maven运行需要JAVA_HOME指向一个可用的JDK。Maven 3.9要求JDK 8起步如果公司项目是JDK 17甚至JDK 21一样能用。真正要注意的是你不要装一个Maven 3.9然后配一个JDK 7环境变量那样mvn命令能执行但构建时会直接报Unsupported major.minor version。2.1 下载入口和国内加速源别再去官网死磕Apache官网的Maven下载页面是Maven的主阵地页面里会给两个选项Source的tar.gz和Binary的zip/tar.gz。我们要的是Binary别手滑下成Source那只是源码进去没有bin目录。问题在于官网服务器在国外直接下3.9.x的zip包经常龟速。我自己的经验是优先用清华大学开源软件镜像站或者阿里云镜像站地址分别是清华https://mirrors.tuna.tsinghua.edu.cn/apache/maven/maven-3/阿里https://mirrors.aliyun.com/apache/maven/maven-3/进去选对应的版本号目录找到apache-maven-3.9.x-bin.zip下载。如果网站封了国外下载地址镜像站几乎是唯一靠谱的选择。下载完之后最好对着官网页面上的SHA-512校验值核对一下文件我在本地遇到过下载的zip包是坏的解压到一半报错校验一遍能避免这种乌龙。3. Windows下安装Maven与环境变量配置的完整套路下载好zip包之后就是大家最熟悉的解压、配环境变量环节但这里面细节非常多。我见过很多新人在这一步卡住不是不会操作而是操作完发现mvn命令就是不能用。先讲目录选择。解压位置我建议放一个专门的开发工具目录比如D:\dev\maven\apache-maven-3.9.x不要直接放C盘里的用户目录也不要放带中文和空格的路径。中文路径在部分旧版插件里会出编码和解析问题空格路径在批处理脚本里也要小心引号匹配。还有一点尽量不要装在C:\Program Files这类目录因为普通用户权限在写日志和改配置时容易被系统拦住后面调用时你可能会被各种Access Denied折腾。3.1 环境变量一步一步配MAVEN_HOME、PATH、JAVA_HOME打开此电脑 → 属性 → 高级系统设置 → 环境变量在这个面板里我们要配两个东西。第一个是新建一个系统变量变量名MAVEN_HOME变量值填你的解压路径也就是到能看到bin目录的那个上层目录例如D:\dev\maven\apache-maven-3.9.x。不要手滑把路径填到bin这一层否则后面%MAVEN_HOME%\bin会变成D:...\bin\bin。第二个是编辑Path变量在变量值末尾加上%MAVEN_HOME%\bin。如果你之前装过其他版本的Maven或者装过某些IDE把Maven路径写进Path里了这里一定要检查一下重复的Maven路径会导致mvn -v出来的是旧版本。Path列表里配置越多越容易互相干扰我通常会精简到只留一个Maven路径。还有一个必备的JAVA_HOME变量。如果机器上已经装了JDK大概率有这个变量变量值指向JDK的安装目录比如D:\dev\jdk\jdk-17不包含bin。Maven的启动脚本靠JAVA_HOME去定位Java找不到JDK的话mvn命令会直接提示JAVA_HOME is not defined correctly。3.2 验证安装mvn -v这一行输出信息怎么读懂配置完环境变量一定要新开一个CMD窗口再执行验证命令因为CMD里的环境变量是在启动时读取的老窗口不会自动刷新。执行mvn -v正常会看到类似下面这样的输出Apache Maven 3.9.9 (8e2a2e6c...) Maven home: D:\dev\maven\apache-maven-3.9.x Java version: 17.0.11, vendor: Oracle Corporation, runtime: D:\dev\jdk\jdk-17 Default locale: zh_CN, platform encoding: UTF-8 OS name: windows 10, version: 10.0, arch: amd64这里要重点看两行Maven home是不是指向你自己的安装目录Java version是不是你预期的JDK版本。如果Maven home显示的路径不对说明Path里还有别的Maven在抢位置如果Java version不对多半是JAVA_HOME配到了别的JDK。如果你用的是macOS配置思路完全一样只是环境变量文件从系统设置换成了~/.bash_profile或~/.zshrc用brew install maven装也行路径稍有不同但settings.xml和本地仓库的配置逻辑跟Windows是一致的。4. settings.xml配置实战本地仓库、镜像仓库、JDK级别一次搞定环境变量配完Maven已经能跑了但离用起来顺手还差最关键的一步——settings.xml配置。这一步是Maven安装配置里最核心、也是网上教程最常被一笔带过的部分。settings.xml在哪个目录决定它的作用范围。Maven安装目录下conf/settings.xml是全局配置影响这台机器上所有用户用户目录下的~/.m2/settings.xml是用户配置只影响当前用户。实际开发中我建议配置在用户目录原因很简单你升级Maven版本时全局配置会被覆盖用户目录下的不会被影响而且IDEA默认读取的也是用户目录下的配置。4.1 第一件事改本地仓库路径Maven默认的本地仓库在C:\Users\你的用户名.m2\repository随着项目越建越多这个目录能膨胀到好几个G。我强烈建议把它挪出C盘放到一个独立的目录比如D:\dev\maven\repository。对应配置是在settings.xml里找到localRepository标签默认是被注释掉的把它打开并填路径即可localRepositoryD:\dev\maven\repository/localRepository改这个路径有两个实际好处一是C盘空间不会被jar包蚕食二是重装系统后D盘仓库还在重新配一次Maven不依赖也能直接跑旧项目省下大量重新下依赖的时间。如果团队有统一规范这个路径通常也会按公司要求固定方便配合CI机的构建缓存。4.2 阿里云镜像仓库配置以及多镜像怎么叠加下载依赖慢是国内Maven用户最痛的槽点。默认的中央仓库服务器在国外拉一个十几个依赖的小项目都能等半天。解决办法就是配镜像仓库。我用最多的是阿里云Maven仓库在settings.xml里的mirrors节点添加如下配置mirror idalimaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror这里mirrorOf写的是central意思是只拦截中央仓库的请求。很多人图省事会写成*表示所有仓库都走这个镜像。我不建议这么干因为公司如果有私有仓库Nexus或者项目里配置了特殊仓库把所有请求都劫持走轻则下载失败重则把私服上的内部构件路径搞乱。如果你还想再叠加一个备用镜像比如腾讯云或者华为云的仓库要注意mirror不是合并关系而是按顺序匹配Maven会使用第一个匹配当前仓库的mirror。所以可以按优先级排好mirrors mirror idalimaven/id namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror mirror idtencent/id nametencent maven/name urlhttps://mirrors.cloud.tencent.com/nexus/repository/maven-public//url mirrorOfcentral/mirrorOf /mirror /mirrors还有一点要专门提醒现在Maven新版本对HTTP协议仓库有限制3.8.1之后的版本如果你把镜像地址写成http://开头会直接提示镜像被阻断报错里带Blocked mirror字样。镜像地址一律用https避免踩这个暗坑。配置文件改完可以用mvn help:effective-settings这个命令查看最终生效的配置里面会把全局和用户级settings合并后的结果打印出来。第一次跑这个命令会下载插件等一会儿是正常的。4.3 用一个profile固定JDK编译级别Java项目最常见的编译级别不对问题表现是代码在本机跑得好好的同事拉过去打包就报invalid target release或source option 7 is no longer supported。这个问题的根源在于Maven默认的编译级别跟你本机JDK不匹配。你可以在settings.xml里加一个激活的profile让所有项目默认使用JDK 17或你需要的级别profiles profile idjdk-17/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target /properties /profile /profiles加了这段配置所有从这台机器构建的Maven项目默认都按Java 17编译不需要在每个项目的pom里反复声明。当然如果某个项目本身在pom里指定了不同的版本项目内的配置优先级更高不会冲突。4.4 配置好之后再确认一遍配置好settings.xml之后建议先跑两条命令验证不要直接打开IDEA导项目。第一条是mvn help:system它会显示当前使用的工作目录、本地仓库路径、系统属性和JDK信息。第二条是mvn help:effective-settings看镜像、本地仓库、profile有没有按预期生效。我在教别人配Maven时总强调一个习惯把settings.xml当成项目配置来管理。改动任何一个节点前先复制一份备份因为配置错误不会报语法错误而是会在某次构建时给你一个莫名其妙的依赖下载异常到时候排查起来特别费劲。5. 在IDEA里把Maven设置调明白一处配置处处顺畅命令行里的Maven配好了接下来就是IDE。很多人觉得IDEA能自动识别Maven不需要额外配置其实那是IDEA用自己的内置Maven在工作。版本可能有差异settings.xml也不会读你改过的用户配置最后出现命令行能打包IDEA里依赖全爆红的诡异现象。所以我到了新机器配置完命令行的第一件事就是打开IDEA进入Settings → Build, Execution, Deployment → Build Tools → Maven把三个地方改好。5.1 三个关键设置Maven home、User settings file、Local repositoryMaven home path那里选择你解压的Maven目录而不是用Bundled默认项。选好之后User settings file这一栏要勾选Override然后填上~/.m2/settings.xml的路径。这时候Local repository一栏会自动跟着settings.xml里的localRepository更新如果没有自动更新手动点一下刷新按钮。这三个设置的含义分别是让IDEA用哪个Maven程序、读哪份用户配置、依赖jar包下载到哪里。三者统一之后IDEA里的构建结果和命令行不会有偏差。5.2 搭配Runner配置让默认命令和模板加速在同一个Maven设置页面往下拉还有Runner区域这里面的VM Options和Properties很多人不注意。我建议在VM Options里加上一行-DarchetypeCataloginternal它的作用是新建项目时Spring Initializr或Maven骨架不再从网上远程拉取模板列表直接用本地缓存避免新建项目卡在Downloading archetype-catalog.xml这个步骤半天。另外如果IDEA里构建大项目频繁OOM可以在VM Options里加-Xmx1024m甚至更大。maven打包本身是独立进程但IDE内部索引和构建工具也吃内存适当调大能减少很多莫名报错。5.3 导入项目后依赖爆红先别删重装遇到IDEA导入Maven项目后依赖全部标红最常见的三个原因按概率排序第一是IDEA没有用你配置的settings.xml还在用内置Maven连中央仓库下载慢甚至会超时第二是本地仓库里有上次中断下载留下的.lastUpdated文件这种文件会让Maven误以为依赖不存在第三是JDK版本和项目要求的版本不一致。第三个问题尤其容易骗到新手。你看到一个报错说cannot resolve symbol但项目结构里其他文件都正常这时候先看Project Structure里Project SDK是多少。我自己帮人排查了十几次这类问题十有七八是project SDK没切到项目要的JDK版本。6. 命令行实操从clean install到依赖树排查把命令用到点子上配置再熟不会用命令行就等于只学了一半。因为公司的CI/CD脚本、运维同事的打包命令、以及你自己排查问题时绝大多数场景还是在终端里跑Maven。6.1 clean install到底干了些什么mvn clean install是出现频率最高的命令甚至已经成了很多团队的肌肉记忆。拆开来看clean是独立生命周期负责删除target目录install属于默认生命周期它会按阶段顺序执行validate、compile、test、package、verify、install最终把构建产物安装到本地仓库。所以mvn install不只是一个安装操作它把编译、测试、打包全部走了一遍再install到本地仓库。team里两个人做模块依赖开发时A模块改动后执行mvn clean installB模块才能拿到A的最新版本。中途跳过测试的写法是-DskipTests注意它只是跳过测试执行照样编译测试代码。如果想连测试代码编译都跳过用-Dmaven.test.skiptrue。实际交付时一般用后者更省时间但本地开发我建议还是跑一下测试提前暴露问题。6.2 常用命令组合速查这里我整理了一份给自己团队新人用的命令速查表覆盖最常见的场景。使用场景命令只编译不打包mvn compile编译并运行测试mvn test打包jar/war不跑测试mvn clean package -DskipTests安装到本地仓库供其他模块引用mvn clean install -DskipTests跳过测试代码的编译mvn clean install -Dmaven.test.skiptrue只构建指定模块mvn clean install -pl 模块名 -am查看依赖树mvn dependency:tree -Dverbose分析无用依赖mvn dependency:analyze其中-pl和-am这对参数在多模块工程里非常实用。-pl指定要构建的模块-am表示同时构建它的依赖模块。只改了其中一个子模块时用这两个参数能把构建时间从分钟级压到几十秒。6.3 依赖冲突排查NoSuchMethodError的元凶很多人被依赖冲突折磨过代码本地能过一到服务器上就抛NoSuchMethodError或者ClassNotFoundException。这通常不是代码问题而是同一个类被两个不同版本的jar包打包了JVM按classpath顺序加载了旧版的那个。排查的第一步就是看依赖树。执行mvn dependency:tree -Dverbose输出会列出所有依赖和它们的传递依赖。看到同一groupId和artifactId出现两次但version不同基本就能锁定冲突点。解决方式有几种在pom里对多余的传递依赖加exclusion或者直接升级引发冲突的依赖到统一版本。这里要提醒一下千万别图省事把所有传递依赖都exclusion掉那样很可能另外一个功能就悄悄挂了。改一个跑一次测试稳扎稳打。7. 常见问题排查实录Maven安装与配置里最容易踩的10个坑配置Maven这件事本身不难难的是报错信息五花八门。我在日常支持同事的过程中积累了一些高频问题写成速查表放在这里碰到对号入座就行。报错/现象排查方向mvn不是内部或外部命令环境变量Path没配好或新开CMD了吗mvn -v显示的是旧版本Path里有多个Maven路径保留一个JAVA_HOME is not defined correctlyJAVA_HOME指向了JRE或路径带bin下载依赖特别慢镜像仓库还没配或mirrorOf写错中央仓库的jar包无法下载镜像地址用了http新版本Maven会阻断IDEA里依赖标红检查IDEA的Maven配置是否指向你的settings.xml项目编译版本不对检查profile里的maven.compiler.source/target某个jar包明明在本地仓库却一直读不到删除对应目录下的.lastUpdated文件再重新构建中文日志乱码Maven的platform encoding显示UTF-8但CMD控制台代码页是GBK改chcp 65001构建时权限不足Maven解压或仓库目录被放在需要管理员权限的位置7.1 一个经常被问到的需求两个本地仓库怎么合并我经常被问到我电脑上装了新旧两个版本的Maven形成两个repository目录想合并成一个有什么好办法Maven只支持一个localRepository所以合并不是配置层面的事情本质上就是文件系统的合并。repository目录的结构是groupId/artifactId/version/jar文件两个仓库结构一致的话直接把整个repository文件夹拷到一个目录里即可。如果你担心同名jar版本覆盖就用新一点的版本优先Maven构建时会按pom声明的版本去取不会因为你仓库里多几个版本而出问题。不过还有一种更干净的做法把仓库里那些本地安装的jar抽出来看有没有对应的pom文件如果没有用mvn install:install-file命令把它们重新安装到统一仓库里。这个做法适合那种同事发我了一个内部依赖让我安装到本地的场景命令如下mvn install:install-file -Dfilexxx.jar -DgroupIdcom.company -DartifactIdxxx -Dversion1.0 -Dpackagingjar如果你两个仓库里同一坐标有两个不同版本还是建议先确认当前项目和哪个版本匹配再决定保留哪个。无脑合并虽然大多数时候没事但版本冲突会以非常隐蔽的方式跑出来咬你。7.2 配置排查通用思路每次配完环境出问题我基本按这个顺序排查先mvn -v确认当前生效版本再mvn help:system确认本地仓库路径再mvn help:effective-settings看配置是否被合并最后才打开IDE看它有没有复用命令行配置。这四步走完90%的问题都能水落石出。还有个小技巧IDEA里改完settings.xml没生效时不用重启IDEA在Maven工具窗口点一下刷新按钮或者跑一次mvn help:effective-settings让配置重新加载。写在最后我装Maven这么多年的一点个人习惯装Maven本身不难但Maven环境的维护是一种长期投资。我一般在新机器上做完安装配置后会花五分钟跑一个新项目模板把整个构建流程走通确认没有报警再开始干活。这么做的好处是你能清楚区分我的环境有问题和项目本身有问题省去很多后面排查的时间。另外我始终坚持用一套配置管理所有环境同一份settings.xml、同一个本地仓库、同一个Maven版本。不管是命令行、IDEA还是后面接触到的VSCode它的Java插件也支持在设置里指定maven.settings路径都指向同一套文件。这样配置一次基本就不会再产生在IDEA里能跑终端里却报错这种割裂问题。最后再分享一个让我受益很大的小习惯每次准备调整settings.xml前先复制一份带了日期的备份文件放旁边。Maven配置不像代码有版本管理你很难立刻知道哪次改动引入的问题有个备份就能迅速回滚。别小看这一招关键时刻能救命。