每次带新人跑通项目，第一句话基本都不是“代码在哪个目录”，而是“Maven装了没”。这个场景重复了太多次，我见过的失败方式也五花八门：压缩包下错成了源码包，解压完是个空壳；环境变量配了一半，mvn -v敲下去弹一句“不是内部或外部命令”；更常见的是装是装上了，结果IDE里用的还是它自带的那份，你在命令行里改了半天settings.xml，项目跑起来一点变化都没有。Maven的下载安装这件事，表面上是“下个包、解个压、配个路径”三步走，实际上AM每个环节都有几个不写进官方文档的暗坑。这篇就把整个流程从环境自查、版本选型、分平台安装、环境变量、settings.xml定制到报错排查完整走一遍，每一步都说清楚“为什么这么做”，而不只是“照着敲”。不管你是第一次接触构建工具的学生，还是被同事的乱环境折腾过的老手，照着走一遍，能省掉后面至少两小时的排障时间。

1. 装Maven之前，先把这几个问题想明白

1.1 Maven究竟替我们省掉了哪些活

很多人对Maven的理解停留在“下载jar包的工具”，这个认知会让你在后面所有配置决策上都做错判断。Maven真正的价值是把“构建”这件事从个人经验变成可复现的流程。你想想没有构建工具的年代，一个Java项目要交付，得有人写一份“先编译哪些目录、classpath里加哪些jar、资源文件拷到哪里、最后怎么打成war包”的说明文档，换个人接手就得重新问一遍。Maven把这套东西固化成了一套约定：源码放哪儿、测试放哪儿、产物输出到哪儿，全都有默认位置，你不用写任何配置就能跑mvn package。

再往深一层，Maven管的是依赖的传递性。你引入一个A包，A包自己依赖B包和C包，C包又依赖D包，这层层嵌套如果靠自己手动下载，版本冲突几乎是必然的。Maven通过坐标和依赖调解机制，自动把这些间接依赖拉下来，冲突时按“路径最短优先、先声明优先”的规则帮你选一个。这个能力才是它十几年没被淘汰的根本原因。

所以安装Maven，本质上是给你的机器装一套标准的Java工程运行时环境：它需要一个能跑起来的JVM，需要一个存放所有第三方包的本地仓库目录，需要一份说清楚“去哪个远程仓库拿包”的配置文件。这三样东西齐了，安装才算真正完成。理解了这一点，你就明白为什么很多人“装完”之后依然跑不了项目——他们只完成了第一样。

1.2 三个必须先建立的心智模型：坐标、仓库、生命周期

装之前先把三个概念建立起来，后面配置settings.xml的时候你就知道每一行在干嘛。

坐标是Maven定位一个构件的唯一标识，由groupId、artifactId、version三段组成，偶尔加个packaging或classifier。它相当于给每个jar包发了一个身份证号，全世界唯一。你以后所有依赖写错、包找不到的问题，八成都是这三段里某一段打错了。

仓库分三级：本地仓库、远程仓库（私服或公共仓库）、中央仓库。Maven找包的顺序是固定的——先翻本地仓库，本地没有就去远程仓库问，远程也没有才去中央仓库。本地仓库默认在当前用户目录下的.m2/repository。这个目录会随着你项目做得越多越大，我见过有人做到十几个G，所以后面我会讲怎么把它挪到容量大的盘上。

生命周期是Maven的执行模型，clean、compile、test、package、install、deploy是一条链，你执行后面的阶段，前面的会自动跑一遍。这就是为什么mvn package之前不需要手动mvn compile。理解这条链，你就不会问“为什么我只想打包它却编译了半天”这种问题——因为它本来就这么设计的。

提示：这三个概念如果现在还是一团浆糊，先别急着往下装。花十分钟把这几个词查清楚，比装完之后反复出问题再回头补课划算得多。

1.3 版本怎么挑：稳定优先还是新特性优先

Maven的版本号看一眼就得知道怎么选。3.x系列是当前绝对主力，其中又分几个小分支：较早的3.6.x、中间的3.8.x、较新的3.9.x。我的建议很明确——生产环境跟团队保持一致，个人开发选3.9.x的最新稳定版。

理由不复杂。3.8.x 之后的版本对HTTP仓库的访问策略做了收紧，默认只允许HTTPS，这个变化会让一些老项目直接报“blocked mirror”错误。如果团队里有人还在用3.6，你一个人升到3.9，遇到这类问题时表现会不一样，排查起来很费劲。所以第一原则是跟团队对齐，没有团队就选最新的稳定版本。

至于那些标着 alpha、beta、RC 的版本，个人学习可以碰，别往生产环境上放。构建工具这种基础设施，稳定性远比新特性重要，你不需要它有什么惊喜，你只需要它每次都一样。

版本选错的典型症状是：配置项写法不兼容、插件行为不一致、某些老的settings.xml模板直接失效。我见过有人从旧项目里拷了一份配置过来，结果启动就报错，折腾半天才发现是版本跨度太大。

1.4 装错了会怎样：几种典型的“假成功”

这里得提前说清楚什么叫“装成功了”。很多人以为mvn -v能打印出版本号就完事了，实际上还有三种“假成功”状态，都会在后面某个时刻咬你一口。

第一种是能打印版本但读不到JDK。mvn -v会输出Java版本，如果那行是空的或者报错，说明JAVA_HOME没配好，Maven只是在硬撑。这种状态跑mvn compile立刻崩。

第二种是命令好用但配置不生效。你在conf/settings.xml里改了本地仓库路径，结果发现依赖还是下到默认位置。原因通常是你在用户目录下还有一份settings.xml，而它的优先级更高，覆盖了全局那份。这个坑非常隐蔽。

第三种是命令行装好了但IDE不认。IDE为了“开箱即用”，往往内置一份Maven，你命令行里那套它根本不看。表现就是你改了镜像配置，IDE里下载依赖依然慢得像蜗牛。

后面每一节我都会针对这三种情况给出验证方法，别嫌麻烦，验证一次总比上线前崩一次好。

2. 下载前的环境自查与目录规划

2.1 JDK与Maven的版本对应关系

Maven本身是个Java程序，它运行需要JVM。所以装Maven之前，JDK必须先就位。两者的版本对应关系有一张隐含的表，官方文档里写得不显眼，但踩坑的人不少。

这张表的关键信息是：Maven 3.9 起不再支持 JDK 7。如果你的机器上还留着很老的项目环境，升级Maven之前先确认JDK版本。反过来说，JDK 8 跑3.9完全没问题，不存在“越新越好”的强制要求。

还有个容易被忽略的点：Maven运行时用的JDK和你项目编译用的JDK可以是同一个，但编译目标版本要单独指定。很多人以为换了JDK 17，Maven编译出来的就是17的字节码，其实不一定，得看pom.xml里的maven.compiler.source和target，或者插件配置。这块后面在验收环节会讲到。

2.2 三条命令摸清现有环境

动手下载之前，先花一分钟做环境体检。三个平台通用，命令都是在终端（Windows下叫命令提示符或PowerShell）里敲。

java -version echo %JAVA_HOME% # Windows CMD echo $JAVA_HOME # macOS / Linux mvn -v

第一条确认JDK在不在、版本是多少。注意java -version输出的是JRE版本信息，如果只装了运行环境没装开发工具包，这条能过但后面会出问题。判断方法是再看一眼javac -version，能打印出版本号说明JDK装全了。

第二条确认JAVA_HOME有没有配。这条最容易被忽略——很多人装JDK时勾选了“自动配置环境变量”，实际只配了PATH没配JAVA_HOME。PATH能让你敲java命令，但Maven需要的是JAVA_HOME指向JDK根目录。如果这条输出是空的或者原样回显了%JAVA_HOME%，说明没配。

第三条如果已经有输出，说明你机器上装过Maven，先看清楚它的安装路径和版本，别急着装第二份。有些IDE会自带一份，路径通常在IDE安装目录下面，mvn -v输出里的Maven home那一行会告诉你具体在哪。

2.3 安装路径怎么选才不给自己挖坑

路径选择这件事，值得单独拎出来说，因为它是后续所有问题的源头。

第一条原则：路径里不要有中文、不要有空格。这不是Maven的毛病，是大量Java工具链的通病。C:\Users\张三\apache-maven-3.9.9这种路径，编译时可能报“找不到类”，日志里一堆乱码，你查半天查不出来。同理，D:\Program Files\这种带空格的路径也躲开，虽然现代工具大多能处理，但总有插件在拼命令行的时候忘了加引号。

第二条原则：装到一个你以后找得到的固定位置。我个人的习惯是统一放在某个盘的根级目录下，比如D:\dev\下面，JDK、Maven、Node之类的工具全在那儿，井井有条。Windows下不推荐装到C:\Program Files，因为写权限问题会让你后面改配置、加插件时频繁遇到权限报错。

第三条原则：解压后的目录名里带版本号。不要图省事改成maven或者apache-maven，就保留apache-maven-3.9.9这种原名。原因是以后你可能需要同时装两个版本做兼容测试，带版本号的命名能让你一眼分清。同时升级的时候直接解压新版本，改一下环境变量就切过去了，旧版本还能留着回退。

macOS和Linux下，如果你希望所有用户都能用，可以放到/opt/下面；只给自己用的话放用户主目录下的~/tools/之类的地方也完全没问题。区别只在于权限管理和环境变量写在哪份配置文件里。

2.4 下载页面上该选哪个包

打开官方下载页之后，你会看到好几类压缩包，列出来容易挑花眼。判断规则其实很简单：

选bin结尾的包，Windows用zip，macOS和Linux用tar.gz。别下成src包，这是新手最常犯的错——解压出来一堆源码目录，没有bin、没有conf，敲什么命令都不好用，然后怀疑人生。

下载完之后建议做一次校验，尤其在内网或网络不稳定的环境下。校验方式很简单：把.sha512文件和压缩包放在同一目录，用系统自带工具算一遍哈希值对比。这一步花不了三十秒，但能避免“文件下了一半”这种极难排查的问题——损坏的压缩包有时候能正常解压，里面的class却是不完整的，跑起来报各种莫名其妙的错。

3. 三个平台的安装实操

3.1 Windows：解压、改配置、配环境变量

Windows下的安装本质上是三步：解压到目标目录、配置环境变量、验证。

解压这一步没什么讲究，用系统自带的解压功能或者任意解压工具都行，解压到你在 2.3 节选好的路径。解压完打开目录看一眼，应该能看到bin、conf、lib、boot这几个目录，看到bin里面有mvn.cmd和mvn两个文件，说明包是对的。

接下来配环境变量。Windows下有两个层次：用户变量和系统变量。个人开发机配用户变量就够了，不需要管理员权限，也不会影响其他账户。如果你是多用户共用的机器，或者希望所有账户都能用，再配系统变量。

需要设置的是两个：

• 新建MAVEN_HOME，值为你的解压路径，比如D:\dev\apache-maven-3.9.9。注意不要带\bin结尾，这是高频错误，多写一层bin会让Maven找不到自己的家目录。
• 编辑PATH，新增一项%MAVEN_HOME%\bin。

配完之后有一个关键动作：关掉所有已经打开的终端窗口，重新开一个。环境变量是在终端启动时读取的，老窗口读的是旧值。这一步不做的后果是你会以为配置没生效，反复检查发现配置明明是对的，陷入自我怀疑。

验证方式就是mvn -v。如果提示“不是内部或外部命令”，按顺序排查：PATH里那一项拼写对不对、MAVEN_HOME值对不对、%MAVEN_HOME%\bin下面是不是真的有mvn.cmd。这三条对上了基本不会失败。

注意：Windows下还有一个历史遗留变量叫M2_HOME，那是很早版本用的，现在写MAVEN_HOME就够了。如果你在别人的教程里看到M2_HOME，不必跟着配，配了也不影响，但属于多余动作。

3.2 macOS：压缩包与包管理器两条路

macOS下有两种装法，各有利弊，我按适用人群分开说。

压缩包安装适合需要精确控制版本、或者机器上有多个项目要求不同Maven版本的情况。流程是：下载tar.gz包，解压到一个固定目录，然后配置环境变量。解压命令很简单：

tar -xzf apache-maven-3.9.9-bin.tar.gz -C ~/tools/

环境变量要写进当前shell的配置文件。这里要注意shell类型：较新的macOS默认是zsh，配置文件是~/.zshrc；老的或者手动切过的可能是bash，配置文件是~/.bash_profile。写错文件的表现是“配置了但没生效”，非常容易让人抓狂。不确定的话用echo $SHELL看一眼。

echo 'export MAVEN_HOME=$HOME/tools/apache-maven-3.9.9' >> ~/.zshrc echo 'export PATH=$MAVEN_HOME/bin:$PATH' >> ~/.zshrc source ~/.zshrc

这里有个细节值得说：PATH的拼接顺序决定了同名命令哪个优先。$MAVEN_HOME/bin放在前面，你新装的这个版本就优先于系统里可能存在的其他版本。如果放后面，可能被别的版本抢先。

包管理器安装适合只想快速有个能用的环境、不关心具体版本号的场景。一条命令搞定，升级也方便。代价是你对安装位置和版本的控制力弱一些，而且它装的可能不是你想要的版本。具体用哪条命令取决于你机器上装了哪个包管理器，这个不展开，敲之前先确认工具在不在。

两条路我都用过，个人建议：要认真做Java开发，用压缩包方式。理由是你必须知道自己的环境装在哪、怎么切版本，这个认知在排查问题时值千金。包管理器装的东西太“黑盒”了，出问题时你连它的目录结构都不熟。

3.3 Linux：解压安装与系统级目录

Linux下的流程跟macOS的压缩包方式基本一致，区别主要在目录选择和权限处理。

如果只给当前用户用，解压到家目录下的某个工具目录即可，环境变量写进~/.bashrc或~/.bash_profile（取决于你的发行版和shell）。如果是多人共用的服务器，通常会解压到/opt/下面，然后通过/etc/profile.d/下的一个脚本文件来做全局环境变量，这样每个用户登录都会加载。

sudo tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/ sudo tee /etc/profile.d/maven.sh > /dev/null <<'EOF' export MAVEN_HOME=/opt/apache-maven-3.9.9 export PATH=$MAVEN_HOME/bin:$PATH EOF source /etc/profile.d/maven.sh

这种写法比直接往/etc/profile末尾追加内容更规范，好处是升级或者卸载时只要改一个独立文件，不会把系统主配置搞得一团糟。我在维护过多台构建机之后养成这个习惯，值得推广。

还有一点容易被忽略：服务器上往往没有图形界面，JAVA_HOME必须显式配。有些JDK安装包会往PATH里丢一个java链接，看着命令能用，但JAVA_HOME是空的，Maven启动就直接报错。所以配完Maven的环境变量，一定顺手确认一下JAVA_HOME也在maven.sh里配好了。

3.4 环境变量的三种写法与优先级

环境变量这块我总结出三种常见写法，各有适用场景，混用的时候要清楚优先级。

第一种是全局系统级，Windows下是系统变量，Linux下是/etc/profile.d/。影响所有用户，适合公用机器，但这台机器上所有人都被绑定到同一个版本。

第二种是用户级，Windows的用户变量，Linux和macOS的用户shell配置文件。影响当前用户，是最常用的方式。

第三种是会话级，直接在终端里export，窗口关掉就失效。听起来很鸡肋，实际上排查问题时特别好用——你想临时测一下另一个版本能不能跑，直接在当前窗口覆盖一下变量就行，不用改动任何配置文件。我调试版本兼容问题时常这么干。

优先级从高到低是：会话级 > 用户级 > 系统级。搞清楚这个顺序，你就明白为什么有时候“明明配了新的却不生效”——要么是会话里残留了旧值，要么是用户级覆盖了系统级。

4. 安装后的验证与settings.xml定制

4.1 mvn -v 的输出逐行解读

mvn -v那几行输出信息量很大，值得逐行读一遍，这是判断环境是否真的健康最直接的手段。

Apache Maven 3.9.9 (hash字符串) Maven home: D:\dev\apache-maven-3.9.9 Java version: 17.0.9, vendor: 某JDK发行版 Java home: D:\dev\jdk-17.0.9 Default locale: zh_CN, platform encoding: UTF-8 OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

第一行确认版本号，跟你下载的对不对得上。第二行Maven home是它认为的安装根目录，如果这行指向的路径跟你预期不一样，说明你的环境变量里还残留着别的配置。第三、四行是Java相关的，这两行是重点——如果它们是空的或者跟你的预期不符，说明JAVA_HOME有问题，这种情况下后面几乎所有命令都会出状况。

第五行的platform encoding也值得留意。如果这里是GBK而不是UTF-8，你后面编译含中文注释的代码时可能出现乱码警告。这不是致命问题，但看着难受，而且某些情况下会影响生成的文档。处理方式是在MAVEN_OPTS里加上编码参数。

最后一行的操作系统信息在排查“为什么别人的机器能跑我的不能”时有用，尤其是架构信息（amd64还是aarch64），某些带本地库的依赖对架构敏感。

4.2 settings.xml 放哪里才算生效

这是全文最重要的一节，也是最容易出问题的一节。Maven的配置文件有两个位置，而且要理解它们的关系。

关键在于，这两份不是覆盖关系，是合并关系。Maven会先读全局那份，再读用户那份，同名配置项以后者为准，不同名的配置项则两边的都保留生效。很多教程说“用户级会覆盖全局级”，这个说法不够准确，容易让人以为配了用户级全局的就全废了。

实际影响是什么？假设你在全局的conf/settings.xml里配了镜像，又在用户目录下写了一份只配了本地仓库路径的settings.xml，那么镜像配置依然生效，因为用户那份没配镜像，不算覆盖。但如果你在用户那份里也配了镜像，全局的那个就被盖掉了。

为了避免这种“到底哪个在生效”的困惑，我的建议是：只维护用户级那一份。全局那份保持出厂状态不动，所有定制都写进~/.m2/settings.xml。这样做还有两个额外好处：升级Maven时全局配置被新版本覆盖也无所谓；换机器时只要拷一份文件就能还原你的全套配置。

如果用户目录下没有.m2目录，手动建一个。Windows下~指的是C:\Users\你的用户名，Linux和macOS就是用户主目录。注意这是个隐藏目录，文件管理器默认不显示，得开启显示隐藏文件或者在命令行里操作。

4.3 本地仓库位置与镜像配置

settings.xml里最常改的两块内容，一个是本地仓库位置，一个是远程镜像。

本地仓库默认在~/.m2/repository。如果你的系统盘空间紧张，或者项目特别多导致仓库膨胀到几十个G，就该把它挪走：

<settings> <localRepository>D:/maven-repo</localRepository> </settings>

路径分隔符在XML里建议统一用正斜杠/，Windows下也能正常识别，用反斜杠在某些场景下会被当成转义符，容易出问题。改完这个配置之后，之前下到默认位置的依赖不会自动搬过去，新位置相当于一片空白，第一次构建会重新下载一遍。所以这个操作最好在环境刚搭好的时候做，别等项目做了一半再改。

镜像配置解决的是下载速度问题。默认的中央仓库在国外，网络往返链路长，在国内环境下拉取依赖经常慢到让人怀疑网络断了。换成国内的公共镜像站点能明显提速：

<mirrors> <mirror> <id>public-mirror</id> <name>公共镜像仓库</name> <url>https://你选用的镜像站点地址/repository/public</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors>

几个参数的含义：id是自定义标识，随便起名但别跟已有的重复；url是镜像站的地址，这个必须去镜像服务提供方的页面上复制，不同家的路径规则不一样，抄错了只会得到一个404；mirrorOf最关键，central表示这个镜像只代理中央仓库，不干涉你在pom.xml里自己声明的其他仓库。有些教程会让你写*，意思是代理所有仓库——这个写法在项目里配了私有仓库的场景下会出大问题，私有仓库的请求也被转发到公共镜像上，结果就是包找不到。除非你明确知道自己在干什么，mirrorOf就写central。

还有个小技巧：如果你确实需要同时用镜像和私有仓库，可以写成*,!私有仓库id的形式，星号排除掉特定的那个，这个语法知道一下就行，用到的时候再查。

4.4 让IDE认准你自己装的这套Maven

命令行装好只是第一步，IDE那边还得单独交代一句，否则它大概率会用自带的版本。

打开IDE的设置界面，找到构建工具相关的配置区域，里面通常有三个关键项需要改：

• Maven主目录（Maven home path）：指向你自己的安装路径，别选“Bundled”那个选项。选完之后路径栏下面会显示出版本号，核对一下对不对。
• 用户配置文件（User settings file）：指向~/.m2/settings.xml，记得勾上“覆盖”那个复选框，否则IDE可能还在用别的配置。
• 本地仓库（Local repository）：正常会自动读出来，如果显示的还是默认路径，手动改成你配置的那个路径。

改完之后有个动作必须做：刷新一下项目的Maven配置。IDE侧边栏的Maven面板里有个刷新按钮，点一下让它重新拉取配置。不做这一步，你改的配置在项目层面不生效，还是老样子跑。

我踩过的最深的一个坑是：明明所有配置都改对了，下载依赖依然慢。查了很久才发现IDE里挂着两个Maven项目，其中一个是之前导入的旧项目，它用的是另一套配置。处理办法是在IDE里把项目关掉重新导入，或者直接清一下IDE的缓存目录。所以配置改完之后，如果效果不对，先想想是不是有多个项目实例在互相干扰。

4.5 一次完整的“拉依赖”验收测试

配置改完，怎么确认真的生效了？别靠肉眼检查配置，用一条命令做端到端验证。

mvn help:system

这条命令做的事很实在：它会打印出当前生效的全部环境信息，包括你配置的本地仓库路径、settings.xml的实际位置、JAVA_HOME、系统属性等等。看几个关键项：

• user.home和user.dir对不对
• java.home指向的是不是你要的JDK
• maven.repo.local是不是你配置的路径

如果这几个都对，说明配置成功加载了。接下来做一次实际的依赖下载验证：随便找个有pom.xml的空项目，敲：

mvn dependency:resolve

这条命令会把pom.xml里声明的依赖全部拉下来。观察两件事：下载速度是不是明显比默认仓库快，以及下载下来的文件是不是落在你配置的本地仓库目录里。这两个都符合预期，环境就彻底通了。

如果想看得更细，加上-X参数跑调试模式，输出会非常啰嗦，但里面能看到每个仓库的请求记录，包括用了哪个镜像、走的是什么协议。只在排查问题时用，平时别加，日志量太大反而看不清重点。

5. 报错现场：常见问题与排查路径

5.1 命令找不到的几种可能

“不是内部或外部命令”或者“command not found”，这个报错出现频率最高，但原因不止一种，得按顺序排除。

第一层：PATH里到底有没有那一项。Windows下echo %PATH%，macOS和Linux下echo $PATH，肉眼过一遍有没有你的Mavenbin目录。注意看是不是拼成了%MAVEN_HOME%\bin\这种尾部多一个反斜杠的形式，大多数情况下没问题，但极个别环境会有影响，规范写法就不带尾部符号。

第二层：那一项展开之后指向的目录是不是真实存在。如果MAVEN_HOME配错了，PATH展开出来是个不存在的路径，系统不会报错，只是找不到命令。手动在文件管理器里导航一次，确认bin/mvn.cmd确实在那儿。

第三层：终端窗口是不是旧的。这个前面说过，但现在再说一遍，因为它是最容易被忽略的原因。改完环境变量后重新开窗口，判断标准很简单——新窗口打开时环境变量才重新读取。

第四层：MAVEN_HOME是不是多写了\bin。写了的话PATH就变成...\apache-maven-3.9.9\bin\bin，多嵌套一层，命令自然找不到。

这四层按顺序查完，基本没有找不到的情况。我给新人排查时都是让他们从第一层开始报结果，通常问到第二层就发现问题了。

5.2 JAVA_HOME相关报错的排查

跟JAVA_HOME有关的报错有好几种形态，症状不同，根因往往是同一个。

症状一：The JAVA_HOME environment variable is not defined correctly。这只是最直白的，说明JAVA_HOME没配或者配的路径下找不到JDK。

症状二：JAVA_HOME should point to a JDK not a JRE。这个更有意思，说明你JAVA_HOME指向的是一个只含运行时的目录。判断方法是看那个目录下有没有bin/javac这个文件——只有java没有javac，就是JRE。现代JDK安装包通常不再单独分发JRE，但如果从某些渠道装的老版本或者精简版，可能出现这种情况。

症状三：mvn -v能过但mvn compile报找不到符号。这种最隐蔽，说明JAVA_HOME指向的JDK版本和代码要求的版本不匹配，或者JAVA_HOME指向了一个残缺的目录。

统一处理办法：先确认JAVA_HOME值不含\bin结尾（这跟MAVEN_HOME的坑一样），再确认那个目录下bin/javac存在，最后确认版本匹配。三个确认做完，问题基本解决。

macOS下还有个特殊情况：系统自带的JDK可能通过一个软链接暴露，看起来路径对，实际指向一个不存在的位置。用ls -l看一下软链接的实际目标，或者直接用/usr/libexec/java_home -V列出所有已安装的JDK，挑一个真实的路径填进去。

5.3 依赖下载卡住与超时

这个问题的表现是mvn命令执行到一半卡住，日志停在某个Downloading from不动，几分钟后报超时。原因通常是网络链路问题，不一定是你的配置错了。

排查顺序建议这样走：

第一步，确认镜像配置是不是真的生效了。跑mvn help:effective-settings，它会合并计算出一份实际生效的配置并打印出来。搜一下mirrors那段，看看里面有没有你配置的镜像、url是不是你写的那个。如果这里没有，说明配置没加载，回到 4.2 节查配置位置。

第二步，确认镜像地址能不能直接访问。用浏览器或者命令行工具访问一下那个地址，看看是不是返回正常响应。有些镜像站点对路径有要求，URL少一段就404。

第三步，看是不是某个特定依赖的问题。如果只有某一个包卡住、其他包都正常，那可能是这个包在镜像站上确实没有。这种时候可以试着在pom.xml里为这个依赖单独声明仓库，或者换个版本。

第四步，考虑是不是本地缓存出了问题。本地仓库里某个包下载了一半，留下一个.lastUpdated后缀的标记文件，Maven会认为这个包下载失败过，短期内不再重试。处理办法是找到对应目录，把.lastUpdated文件删掉再重试。批量清理的话可以写个脚本扫一遍，这个技巧在长期维护中很有用。

提示：-o参数可以强制Maven以离线模式运行，完全不访问网络，只用本地仓库里已有的包。这个参数在确认“问题出在网络还是出在本地配置”的时候特别好用——加上-o能跑通，说明配置没问题，就是网络访问的事。

5.4 编码问题与中文乱码

编码问题的典型表现是编译时出现unmappable character警告，或者IDE里看到的注释是乱码，或者打包出来的资源文件里中文变了样。

根因是JVM的默认字符集和文件编码不一致。有个细节要注意：从某些JDK版本开始，默认字符集在某些平台上会跟随系统区域设置，同一份代码在不同机器上表现不一样。

处理方式有两个层次。项目级的做法是在pom.xml里显式声明源码编码：

<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties>

这两个属性只影响Maven读源码和生成报告的行为，是最该配的。配了之后大部分编码警告会消失。

环境级的做法是给Maven的JVM加参数：

export MAVEN_OPTS="-Dfile.encoding=UTF-8"

Windows下用set MAVEN_OPTS=-Dfile.encoding=UTF-8，或者通过系统属性面板设置成用户变量。这个参数影响的是Maven自身的JVM，也就是日志输出和各种副产物文件的编码。

我的经验是：两个都配。项目级的保证代码跨机器行为一致，环境级的保证日志不乱码。只配一个的话，总会在某个环节冒出来恶心你一下。

5.5 多版本共存的切换方案

做久了必然会遇到需要同时维护两个版本的情况——老项目要求旧版本，新项目用新版本。这时候别想着让两个版本和平共处，直接做显式切换更可靠。

方案一是改环境变量切换。两个版本解压到不同目录，把MAVEN_HOME指向要用的那个，重开终端。优点是干净彻底，缺点是要改配置、要重开窗口，切得频繁的话很烦。

方案二是写脚本切换。在shell配置文件里定义两个函数或者别名，一个切到版本A，一个切到版本B，执行就改当前会话的MAVEN_HOME和PATH。这个方式只影响当前窗口，关掉就恢复默认，特别适合临时切。

方案三是项目级锁定。Maven的wrapper机制（mvnw脚本）可以让项目自带指定版本的Maven，运行时自动下载并使用那个版本，不受机器环境影响。团队协作场景下这是最优解，因为所有人的构建版本完全一致。代价是第一次运行要下载一份Maven，离线环境下用不了。

我个人在日常开发中用的是组合拳：机器上配一个默认版本（最新稳定版），需要测兼容性的时候用脚本在当前窗口临时切。团队项目统一加wrapper，彻底摆脱“你机器上是什么版本”这个问题。

6. 我踩过的坑与长期维护建议

6.1 别用管理员权限装到系统目录

这一条单独拎出来讲，因为后果最严重。把Maven装到需要管理员权限才能写的目录（Windows的Program Files、Linux的/usr/local某些子目录），短期内看不出问题，长期会积累一堆麻烦。

第一，改配置需要提权。你在conf/settings.xml里改一行镜像配置，保存时弹个权限框，用编辑器打开还要以管理员身份运行，日常操作被反复打断。

第二，插件或工具可能会往Maven目录里写东西（比如某些缓存或下载的扩展），写不进去就报错，报错信息还很难懂。

第三，多用户环境下一旦有人以管理员身份改了配置，其他人莫名其妙受影响。

正确做法是装到用户可写的目录，所有配置改动都不需要提权。Windows下建议在非系统盘建一个开发工具目录统一管理，Linux下装到/opt需要sudo解压但后续读取和执行都不需要提权，这是可以接受的。

6.2 配置文件要版本化备份

settings.xml这份文件其实是你的环境资产，里面沉淀了镜像配置、本地仓库位置、代理设置、认证信息等等。丢了重新配一遍，光是回忆“上次那个 URL 是什么”就够烦的。

我的做法是把这份文件纳入个人配置的版本管理。提到某个统一的地方存着，换机器或者重装系统时拷过来就用。同时改配置的时候养成留注释的习惯：

<!-- 2024-xx 换成XX镜像，解决下载慢的问题 --> <mirror> ... </mirror>

注释里别看只写一行，半年后你自己都会感谢当时的自己。尤其是那种“为什么这里要这么写”的配置，不写注释根本想不起来。

还有个小习惯值得推广：改配置前先复制一份备份，命名成settings.xml.bak之类。改崩了直接换回来，比对着报错反复试要快得多。这个动作只花三秒钟。

6.3 升级Maven的正确姿势

升级这件事，很多人是直接下个新版本解压，改一下环境变量就完事。这么做能跑，但漏掉了一些收尾动作，容易留下隐患。

完整流程应该是：新版本解压到新目录，不要覆盖旧目录；改MAVEN_HOME指向新目录；新开终端验证版本号；跑一次mvn help:system确认配置还生效；找个真实项目完整构建一次，确认没问题。

这一步“找个真实项目构建一次”别跳过。有些版本升级会改变插件默认行为，或者对某些配置项的解析规则有调整，只看版本号是发现不了的。我就遇到过一次升级后打包产物结构变了，因为在本地跑了个mvn -v就以为没事了，结果部署时才发现。

旧版本目录先别删，留个一两周。真出了问题，改一下环境变量就能回退，这是最省时间的应急手段。确认稳定之后再清理。

6.4 团队环境一致性的小技巧

带团队或者协作开发时，环境不一致造成的问题能占到排障时间的一半。“我这能跑你那儿跑不了”这种对话，根源往往就是Maven版本不同或者settings.xml配置不同。

几条实操建议：

一是在项目里维护一份环境说明文档，写清楚推荐的Maven版本、JDK版本、必须配的镜像。别指望口头传达，新人进来照着文档走一遍就行。

二是把构建相关的配置尽量收进pom.xml，少依赖个人机器上的settings.xml。比如编码配置、插件版本、编译目标版本，这些写进pom.xml就跟着项目走了，换台机器行为一致。只在settings.xml里放那些真的跟个人环境相关的东西，比如本地仓库路径和镜像。

三是CI环境里显式固定Maven版本。构建服务器上千万别用“默认版本”这种模糊表述，明确写死版本号，保证每次构建的环境可复现。

四是统一本地仓库的路径规范。团队里如果大家都用默认路径也就算了，一旦有人改过，就要在文档里说清楚，避免出现“我按文档改了路径结果依赖要重新下”的困惑。

最后分享一个我在实际维护中养成的小习惯：每台新机器配完之后，把mvn -v和mvn help:system的输出各存一份到一个文本文件里，命名为机器名加日期。下次出问题时，把当前输出和这份存档一比，差异一目了然。这个做法听起来笨，但在排查“为什么这台机器就是不行”的时候，往往比任何思路都快。