1. 先把 Maven 这件事说清楚：它到底解决什么问题

聊 Maven 下载安装之前，我想先花点篇幅把“这东西是干嘛的”讲透。因为我在带新人的时候发现一个很普遍的现象：很多人装 Maven 装得挺顺，mvn -v也能出结果，但对着一堆pom.xml里的标签发呆，不知道自己在配置什么，出了错就只能搜报错原文，一搜一整天。装软件这件事本身只有十分钟，真正耗时间的是理解它为什么存在。

Maven 是 Java 平台上用来做项目构建和依赖管理的工具。把这句话拆开看：项目构建指的是编译源码、跑测试、打包成 jar 或 war、安装到本地仓库、发布到远程仓库这一整套动作；依赖管理指的是你的项目要用到哪些第三方库，这些库又依赖哪些别的库，版本之间冲不冲突，从哪下载，缓存在哪。这两件事在 Maven 出现之前，是纯手工的。

我见过早期项目的做法：项目根目录下扔一个lib文件夹，里面堆着几十个 jar 包，名字类似commons-lang3-3.12.0.jar。谁要用哪个版本，从同事那里拷一份过来。结果就是同一个 jar 在三个项目里躺着三个不同版本，某天线上报NoSuchMethodError，排查半天发现是 A 项目打包时把老版本的 jar 也带进去了。这种问题在 Maven 体系下基本不会发生，因为它用一个叫坐标的东西唯一标识每一个构件，用一棵依赖树把传递依赖算清楚，冲突的时候有明确的调解规则。

所以 Maven 的下载安装，装的不是一个“能编译 Java 的软件”，装的是一整套项目结构和协作约定的入口。你装完它，等于接受了一套“约定优于配置”的规则：源码放src/main/java，资源放src/main/resources，测试代码放src/test/java，编译产物进target。你不按这个结构放东西，Maven 就找不到文件，它会很干脆地给你报错，而不是猜。

1.1 从“手动拷 jar”到“声明式依赖”的思维转变

刚接触 Maven 的人最容易卡住的地方不是命令，而是思维。以前你写代码要用 log4j，动作是“去官网下载 jar，扔进项目，右键 Add to Build Path”。现在你的动作是：在pom.xml里写三段坐标，然后让 Maven 去下载。

<dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.20.0</version> </dependency>

这个转变的深层价值在于：依赖信息变成了项目源码的一部分，可以进版本控制，可以 code review，可以被 CI 流水线复现。三年后你回头看某个老项目，不需要去问“当时用的哪个版本的驱动”，pom.xml里写得清清楚楚。而且 Maven 会把下载下来的 jar 缓存到本地仓库，同一台机器上的所有项目共享，磁盘上不会出现同一份 jar 存十遍的情况（除非版本不同）。

这里有个细节值得提前说：本地仓库是一个“全局缓存”，不是“项目私有目录”。这意味着你在项目 A 里下载过的依赖，项目 B 可以直接用，速度很快。但也意味着，如果本地仓库里某个 jar 被下载坏了（网络中断、磁盘异常都可能导致），所有依赖它的项目都会一起报错。后面排查章节里我会专门讲怎么处理这个情况。

1.2 坐标、生命周期、仓库：三个必须建立的概念

我不打算把 Maven 的全部概念讲一遍，但安装完之后你会立刻撞上这三个词，先有个印象会顺利很多。

坐标是 Maven 世界里每个构件的身份证，由groupId（组织或命名空间，通常是反写的域名形式）、artifactId（项目名）、version（版本号）组成，可选还有packaging（打包类型，默认 jar）和classifier（分类器，用于区分同一版本的不同产物）。你在pom.xml里声明的每一个依赖，本质都是“请给我这个坐标对应的文件”。理解这一点之后，你就明白为什么报错信息经常是Could not find artifact xxx:yyy:jar:1.0，它说的是“这个坐标在仓库里找不到”。

生命周期是 Maven 最反直觉的设计之一。它定义了三套阶段序列：clean（清理）、default（构建）、site（站点生成）。default里依次是validate → compile → test → package → verify → install → deploy。关键点在于：你执行某个阶段，Maven 会自动把它前面的所有阶段都执行一遍。你敲mvn package，它其实跑了 validate、compile、test，最后才 package。这就是为什么有时候你只想打包，却发现测试跑了五分钟还挂了。想跳过就加-DskipTests（跳过执行但仍编译测试代码）或者-Dmaven.test.skip=true（连编译都跳过）。这个区别很多人搞混，我在后面的排查章节会再强调一次。

仓库分三种：本地仓库（默认在你用户目录下的.m2/repository）、远程仓库（中央仓库，以及团队自建的私服）、以及镜像（mirror，是远程仓库的替代地址）。Maven 找依赖的顺序永远是本地仓库优先，找不到才去远程仓库，远程拿回来之后会存进本地仓库。安装配置里最值得花时间打磨的，就是本地仓库位置和镜像地址这两项。

1.3 什么情况下该装，什么情况下可以先放一放

说句实话，不是所有写 Java 的人都必须立刻亲手装一遍 Maven。如果你只是临时跑一个 demo，用 IDE 自带的构建能力，或者用单文件java命令直接跑，完全可以不装。但下面这几种场景，建议你老老实实装一个独立版本：

第一，你要长期做 Java 后端或 Android 相关开发，项目结构是标准的多模块工程，pom.xml是核心配置。第二，你要在工作机上执行打包、部署这类脚本，或者在服务器上跑构建，需要命令行直接调mvn。第三，你已经踩到“IDE 里能跑、命令行跑不了”的坑，说明 IDE 用的 Maven 和你环境里的不是一套，这时候必须有一个明确的、可被脚本调用的 Maven 安装。第四，你要排查依赖冲突、看依赖树，mvn dependency:tree这类命令是利器，绕不开。

反过来，如果你只是想知道 Maven 是什么，看两篇文章就够了，不必折腾环境。安装这件事的价值，只有在真正跑一个构建的时候才体现出来。

2. 安装前的环境盘点：JDK、版本与目录规划

我见过太多“装完不能用”的案例，回过头查，八成问题出在安装之前——JDK 没装、版本不匹配、环境变量指错层目录。所以这一段我建议你一个都别跳，花五分钟看完，能省掉后面一小时的折腾。

2.1 Maven 和 JDK 的版本对应关系

Maven 本身是个 Java 程序，它自己就是用 Java 写的，所以必须先有可用的 JDK 才能跑起来。注意是 JDK 不是 JRE，因为 Maven 在构建过程中需要调用编译器（javac），纯运行环境是不够的。

版本对应这块有个大致规律：Maven 3.8.x 和 3.9.x 系列要求 JDK 8 及以上，这几个版本是目前的主力，兼容性最好。如果你打算用 JDK 17 或 21，Maven 3.9.x 是更稳的选择，因为它在处理新版本 JDK 的一些模块化限制时更完善。至于更新的 Maven 大版本，对 JDK 的基线要求会更高，如果你所在团队的项目还在用 JDK 8，装之前务必确认清楚，别一不小心装了个跑不起来的新版本。

还有一点容易被忽略：Maven 版本和项目里的插件版本是两回事。你装了 Maven 3.9，不代表项目里用的编译插件就是新版本，插件版本由pom.xml里的配置决定。所以偶尔会遇到“我 Maven 明明是新版，怎么编译还报老问题”，这时候要看的是maven-compiler-plugin的配置，而不是 Maven 本身。

2.2 JAVA_HOME 为什么比 PATH 更关键

环境变量这块，我只强调一件事：Maven 启动脚本是靠JAVA_HOME找 JDK 的，不是靠PATH里的java命令。这个区别非常致命。

很多人装完 JDK，把%JAVA_HOME%\bin加进PATH，然后java -version能输出，就以为万事大吉。结果装完 Maven，一敲mvn -v报错说找不到 Java 运行环境。原因是 Maven 的mvn.cmd（Windows）或mvn（类 Unix）脚本里，第一件事就是读JAVA_HOME变量，拼出%JAVA_HOME%\bin\java.exe去执行。JAVA_HOME没设或者设错了，脚本直接退出。

而且JAVA_HOME必须指到JDK 的根目录，不是bin目录。Windows 上正确的写法类似D:\dev\jdk-17，错误的写法是D:\dev\jdk-17\bin。指到bin之后，Maven 会去找D:\dev\jdk-17\bin\bin\java.exe，当然找不到。这个错误极其常见，我在排查问题时第一件事就是让对方面把echo %JAVA_HOME%的输出贴出来。

提示：如果你的机器上装了多个 JDK，切换版本的正确做法是改JAVA_HOME的值，而不是往PATH里塞多个bin目录。PATH的顺序在多 JDK 场景下非常容易失控。

2.3 安装目录规划的三条经验

第一，路径不要带空格，不要带中文。Windows 上别装到C:\Program Files\下面，也别装到桌面上（桌面路径通常含中文用户名）。空格和中文在某些插件的路径拼接逻辑里会出问题，这类问题报错信息还很隐晦，排查成本极高。我习惯在 Windows 上装到D:\dev\下，Linux 上装到/opt/下，路径短、干净、好记。

第二，Maven 解压目录和本地仓库目录分开规划。Maven 解压出来也就十几兆，装在哪个盘都无所谓。真正占空间的是本地仓库，一个中型项目的依赖轻松上到几百兆，多项目共存的话几个 G 很正常。所以本地仓库要单独放到一个空间充足、不在同步盘里的位置。放在 OneDrive、iCloud 这类会实时同步的目录下，极容易出现文件被锁住导致下载失败。

第三，如果是团队协作环境，尽量统一版本和配置。听起来是老生常谈，但差异真的会咬人：有人用 3.6，有人用 3.9，同一个pom.xml解析出来的有效配置可能不同，构建结果不一致，排查时互相怀疑对方的环境。我一般的做法是在团队文档里固定写清楚“Maven 版本 X，JDK 版本 Y，本地仓库路径 Z”，新人入职照着配，能省掉大量无效沟通。

3. 分平台下载与安装实操

接下来是动手部分。我会按 Windows、Linux、macOS 三个平台分别讲，每个平台给完整流程和验证方法。如果你只关心自己用的系统，可以只挑对应的小节看，但验证那一段建议都看一眼，因为“装完怎么确认装对了”这件事，很多人其实没做对。

3.1 Windows：解压式安装与 PATH 配置全流程

Windows 上安装 Maven 的官方方式就是下载压缩包解压，没有安装向导。具体步骤：

第一步，去 Maven 官方站点找到下载页面，选择Binary zip archive那个包（不要选 Source 源码包，源码包是给人看的，不是拿来用的）。下载下来的文件名形如apache-maven-3.9.x-bin.zip。

第二步，解压到一个干净路径。我习惯解压到D:\dev\maven\，最终得到的目录是D:\dev\maven\apache-maven-3.9.x。这个最终目录就是所谓的MAVEN_HOME。解压完之后，进去看一眼，应该能看到bin、conf、lib三个目录。bin里是启动脚本，conf里是settings.xml，lib里是 Maven 自己的 jar。看到这三个目录，说明包没下错。

第三步，配环境变量。打开系统环境变量设置，新建一个用户变量或系统变量MAVEN_HOME，值为D:\dev\maven\apache-maven-3.9.x（注意结尾不要带反斜杠，也别带\bin）。然后在Path里新增一条%MAVEN_HOME%\bin。

第四步，也是最多人漏掉的一步：关掉所有已经打开的终端和 IDE，重新开一个。环境变量的修改对已运行进程不生效，很多人配完变量在原来的命令行窗口里敲mvn -v，报“不是内部或外部命令”，就以为配错了，来回改半天。其实只是窗口没刷新。这个坑我踩过不止一次。

第五步，新开一个命令行窗口，敲mvn -v验证。

3.2 Linux：二进制包部署到 /opt 的标准做法

Linux 上的流程和 Windows 类似，但有几个地方需要注意权限和软链接。

先确认 JDK 就绪：java -version和echo $JAVA_HOME都要有正常输出，且JAVA_HOME指向 JDK 根目录。如果JAVA_HOME为空，先把它配好再往下走。

然后把下载的apache-maven-3.9.x-bin.tar.gz解压到/opt：

sudo tar -zxvf apache-maven-3.9.x-bin.tar.gz -C /opt

解压后建议建一个不带版本号的软链接，这样以后升级 Maven 只需要改软链接指向，环境变量不用动：

sudo ln -s /opt/apache-maven-3.9.x /opt/maven

接着配置环境变量。为了让所有用户都生效，写到/etc/profile.d/下新建一个脚本是最省事的做法：

sudo tee /etc/profile.d/maven.sh > /dev/null <<'EOF' export MAVEN_HOME=/opt/maven export PATH=$MAVEN_HOME/bin:$PATH EOF sudo chmod +x /etc/profile.d/maven.sh

写完要source /etc/profile.d/maven.sh或者重新登录一次才生效。这里有个细节：如果你只在~/.bashrc里配，那么通过某些非交互式方式（比如某些自动化任务）执行命令时是读不到这个变量的，容易在流水线里出问题。写到profile.d下更稳妥。

最后验证：mvn -v。如果报权限错误，检查一下bin/mvn是否有可执行权限，chmod +x /opt/maven/bin/mvn一下即可。

3.3 macOS：包管理器安装与手动安装怎么选

macOS 上有两条路。一条是用 Homebrew 装：brew install maven。优点是省事，升级也是brew upgrade maven一条命令。缺点有两个：一是它可能会顺带装一个自己的 OpenJDK，导致你的JAVA_HOME指向一个你没预期的 JDK，多版本环境里容易乱；二是 Homebrew 装的路径和你手动解压的路径完全不同，团队里有人手动装有人 brew 装，排查问题时路径对不上，沟通成本上升。

另一条路是手动下载 tar.gz 解压，和 Linux 的做法基本一致，只是路径习惯放在/usr/local/或者用户目录下。我个人更倾向手动装，因为路径可控、版本可控、和 Linux 服务器上的布局一致，心理负担小。

如果要配环境变量，注意现在的 macOS 默认 shell 是 zsh，配置文件是~/.zshrc而不是~/.bash_profile。在~/.bash_profile里写半天没生效，八成就是这个原因。写入之后source ~/.zshrc或者重开终端。

3.4 验证安装：mvn -v的输出要怎么看

很多人敲完mvn -v看到一串输出就以为通过了，其实那串输出里有几个关键信息必须核对：

Apache Maven 3.9.x (xxxxxxxx) Maven home: D:\dev\maven\apache-maven-3.9.x Java version: 17.0.x, vendor: ... Java home: D:\dev\jdk-17 Default locale: zh_CN, platform encoding: UTF-8 OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

第一行是 Maven 版本，确认是你装的那个。第二行Maven home确认解压路径没错。第三、四行最要紧：Java home必须指向你想用的那个 JDK。如果这里显示的是某个你完全不认识的路径（比如某个 IDE 内嵌的 JDK，或者系统里另一个版本），说明JAVA_HOME被别的配置覆盖了，这时候构建出来的东西可能和你预期的不一样。最后看platform encoding，如果显示的不是 UTF-8，中文注释和中文资源文件在编译时可能出现乱码，需要额外处理。

注意：mvn -v成功只代表 Maven 能启动，不代表构建能成功。真正的验证是跑一次mvn help:evaluate或者直接建个空项目打包一次，后面第 5 节会讲。

4. settings.xml：真正决定“好不好用”的配置文件

如果说安装是“能用”，那settings.xml就是决定“好不好用”。这个文件的配置质量，直接决定你后续几个月里是顺畅开发还是天天和下载超时、依赖找不到作斗争。我见过太多人装完 Maven 就再也没碰过这个文件，结果每次构建都慢得像蜗牛，还以为是网络问题。

4.1 用户级与全局级的优先级关系

settings.xml有两个位置，理解它们的关系很重要：

Maven 的实际行为是两者合并，用户级覆盖全局级。注意是“合并”不是“替换”，所以你在用户级只写一个本地仓库路径，全局级里的镜像配置依然有效。但如果两边都配了同一个id的 mirror，用户级会赢。

我的建议是：全局配置保持不动，所有个性化配置写用户级。理由很实际——升级 Maven 的时候，conf目录可能被覆盖，你辛辛苦苦改的全局配置就没了；而用户级配置在~/.m2下，和 Maven 安装目录解耦，升级多少次都不受影响。

4.2 本地仓库迁移：别让系统盘被悄悄撑爆

默认的本地仓库在${user.home}/.m2/repository。这个默认值在纯个人开发机上问题不大，但在两类场景下会出事：一是系统盘空间紧张（笔记本常见），二是团队希望把依赖缓存放共享盘统一管理。

改法很简单，在用户级settings.xml里加一行：

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"> <localRepository>D:/dev/maven-repo</localRepository> </settings>

几个必须注意的点：

路径分隔符用正斜杠最稳，Windows 上写反斜杠在某些场景下会被当成转义字符处理，虽然大多数时候没事，但没必要给自己埋雷。路径不要含中文和空格，理由和安装目录一样。如果目录不存在，Maven 会自动创建，但父目录必须有权限。

还有一个非常大的坑：不要把本地仓库放在会实时同步的目录（云盘同步目录、网络映射盘）。这些目录的文件锁行为和普通磁盘不同，Maven 下载依赖时会写临时文件再重命名，同步软件可能在中间插一脚，导致出现大量.lastUpdated后缀的残留文件，表现为“依赖明明下载过，怎么又去下载并且还失败”。如果你的本地仓库已经在同步目录里，赶紧迁出来。

迁出来之后，旧的依赖不用手动拷，第一次构建会自动重新下载。如果嫌慢，可以把旧目录整个复制过去，Maven 认路径不认位置，复制过去就能直接用。

4.3 镜像配置的写法与最容易踩的三个坑

镜像（mirror）的作用是：把对某个远程仓库的请求，转发到另一个地址。国内环境里最常见的用途，是把对中央仓库的请求转发到就近的公共仓库代理，下载速度能快一个数量级。

基本写法如下：

<mirrors> <mirror> <id>internal-public-repo</id> <name>Internal Public Repository</name> <url>https://your-mirror-host/repository/public</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors>

关于地址，不同环境提供的服务不一样，公司私服、云厂商公共仓库、团队自建代理都有可能，具体地址以你所在环境给出的为准；如果暂时没有可用代理，这一整段可以不配，Maven 默认会走中央仓库，只是速度取决于网络条件。

三个坑重点说一下：

坑一是mirrorOf写成了*。星号表示“拦截所有远程仓库请求”，包括项目pom.xml里额外声明的仓库。这会导致什么问题？你项目里需要从某个特定仓库拉一个包，结果这个请求也被转发到镜像地址，而镜像里没有这个包，构建直接失败，报错还看不出是镜像导致的。除非你非常确定镜像里有全量内容，否则写central最稳，或者写external:*（拦截所有外部仓库，但保留本地和文件协议）。

坑二是 mirror 的id和repository的id撞了。Maven 有个规则：如果一个 repository 的id和某个 mirror 的id相同，这个 repository 的配置会被忽略。有些人为了图省事，两边 id 都写成nexus或者central，结果自己写的 repository 配置完全没生效，还以为是配置语法错了。

坑三是公司私服需要认证时，server的id必须和mirror的id严格一致。密码存在~/.m2/settings.xml的<servers>段里，靠id匹配。差一个字符，就会一直报 401，而且报错信息里不会告诉你“你的 id 写错了”。

<servers> <server> <id>internal-public-repo</id> <username>your-account</username> <password>your-password</password> </server> </servers>

注意：密码直接明文写在settings.xml里是有风险的。个人机器上问题不大，但如果是共享构建机，务必做好文件权限控制，或者改用更安全的凭据管理方式。

4.4 代理、离线模式与内存参数

企业内网环境有时需要走代理才能访问外网。settings.xml里可以配<proxies>，指定协议、主机、端口和排除列表。这部分的配置比较机械，照着网络管理员给的参数填就行，需要注意的是<nonProxyHosts>要把内网地址排除掉，否则访问私服的请求也会被代理转发，直接失败。

离线模式是另一个实用开关。mvn -o表示“只用本地仓库，不联网”。什么时候用？服务器构建环境完全断网、或者你想验证本地仓库是否完整（如果离线构建能过，说明依赖都齐了）。反过来，如果离线构建报缺依赖，你就知道要联网补一次。

内存参数MAVEN_OPTS也值得一提。默认堆内存对大多数项目够用，但遇到大型多模块工程，或者依赖树特别深的项目，可能报OutOfMemoryError。这时候设一下：

# Linux / macOS export MAVEN_OPTS="-Xmx2048m -Dfile.encoding=UTF-8" # Windows 命令行临时设置 set MAVEN_OPTS=-Xmx2048m -Dfile.encoding=UTF-8

顺带说一下-Dfile.encoding=UTF-8，这个参数在 Windows 上特别有用，能缓解控制台中文日志乱码的问题。但要注意，它影响的是 Maven 进程自身的编码，项目源码的编码还是由project.build.sourceEncoding控制，两者不是一回事，别指望设一个就把所有乱码问题解决了。

5. IDE 集成与第一个项目的落地验证

命令行能跑，只完成了一半。日常开发是在 IDE 里进行的，IDE 用哪套 Maven、哪个settings.xml、哪个本地仓库，都必须显式指定清楚，否则会出现“命令行构建成功、IDE 里红一片”的经典问题。

5.1 IDE 里必须显式改的三处配置

以主流 Java IDE 为例，Maven 相关设置通常在构建工具的设置面板里，需要确认三个地方：

第一，Maven 主目录（Maven home path）。默认往往是 IDE 内置的捆绑版本。我强烈建议改成你手动安装的那个路径。内置版本的问题在于版本号固定、配置路径固定，出问题时你很难判断用的是哪套。改成外部安装的之后，IDE 和命令行用的是同一套 Maven，行为一致，问题可复现。

第二，用户设置文件（User settings file）。默认指向~/.m2/settings.xml。如果你把配置写在别的地方，这里要勾选覆盖并指定路径。

第三，本地仓库（Local repository）。这一项默认从settings.xml读取，但很多 IDE 提供独立覆盖选项。如果这里显示的还是默认路径，但你的settings.xml里已经改了，说明 IDE 没读到配置，需要勾选覆盖手动指定，或者检查settings.xml路径是否指对了。

还有两个容易被忽略的细节。一是导入时使用的 JDK（有时叫 JDK for importer），它决定 IDE 解析pom.xml时用哪个 Java 版本，如果和项目实际编译版本差太远，会出现依赖解析正常但代码标红的情况。二是运行器的 VM 参数，老版本 IDE 需要手动加-Dmaven.multiModuleProjectDirectory=$MAVEN_HOME，新版本大多自动处理了，但如果你遇到多模块项目在 IDE 里跑不起来，可以往这个方向查。

5.2 用 archetype 生成骨架并跑通第一次构建

验证环境是否真的可用，最好的办法是从零生成一个项目并完整构建一次。在命令行里执行：

mvn archetype:generate \ -DgroupId=com.example.demo \ -DartifactId=demo-app \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DinteractiveMode=false

这条命令会从远程仓库拉取骨架模板，在当前目录下生成一个demo-app项目。命令执行过程中你会看到大量Downloading from ...的输出，这是正常的，第一次跑要下载不少东西。

生成完之后进入目录，执行打包：

cd demo-app mvn clean package

如果环境正常，你会看到构建日志依次经过clean、resources、compiler、surefire（测试）、jar，最后输出BUILD SUCCESS，并且在target目录下出现demo-app-1.0-SNAPSHOT.jar。到这一步，才算真正验证了“下载、安装、配置、构建”整条链路是通的。

这一步常见的一个失败是骨架版本找不到，报Unable to find ... maven-archetype-quickstart。原因通常是骨架模板本身版本比较老，加上镜像站点同步延迟。解决办法是指定一个明确的版本号，比如加上-DarchetypeVersion=1.4，或者换个骨架类型。这类问题不影响你后续正常使用，只是生成模板这一步受影响。

5.3 卡在 Downloading：一条清晰的排查路径

Downloading卡住不动或者反复重试，是安装使用阶段最高频的问题。我一般按这个顺序排查：

先看网络和目标地址是否可达。用curl -I或者浏览器访问一下镜像地址，看能不能正常返回。如果是公司内网，确认是否需要代理或者认证。

再看本地仓库里有没有残留的失败标记。Maven 下载失败后，会在对应目录留下.lastUpdated后缀的文件，并且在一段时间内不会重试，直接报错。清理方法：

# Linux / macOS，清理所有失败标记 find ~/.m2/repository -name "*.lastUpdated" -delete # 强制更新快照和发布版本 mvn clean package -U

-U这个参数是“强制检查更新”，很多“明明私服上有新版本，本地死活拉不到”的情况，加-U就好了。

最后看是不是被镜像策略拦住了。如果是项目里自带的repository配置被mirrorOf: *拦截，表现就是某个特定依赖怎么都下不来，其他依赖都正常。这时候把mirrorOf改成central，或者针对性地加!仓库id排除项。

6. 常见问题速查与避坑清单

这一节是我这些年攒下来的问题清单，按“安装阶段”和“使用阶段”分开，最后给一张速查表。里面的每一条我都在真实场景里见过不止一次，尤其是前几条，几乎每个新环境都会撞上。

6.1 安装阶段的高频报错

报错一：'mvn' 不是内部或外部命令，也不是可运行的程序。这是 Windows 上最常见的一条。三个原因按概率排序：环境变量改完没重开终端（占比最高）；Path里写成了%MAVEN_HOME%（用了反的百分号）；MAVEN_HOME指向了bin目录而不是根目录。排查方法很直接，新开一个命令行，分别执行echo %MAVEN_HOME%和where mvn，两个输出一对就清楚了。

报错二：JAVA_HOME environment variable is not defined correctly。这条报错信息其实很明确，但很多人看不懂。它说的是“我按JAVA_HOME找到了一个路径，但那个路径下面没有bin/java”。所以要么JAVA_HOME没设，要么指向了 JRE 而不是 JDK，要么多写了一层bin。验证方法：在命令行执行%JAVA_HOME%\bin\java -version，能输出就说明路径对，不能输出就是路径错。

报错三：mvn -v输出的 Java home 不是我想用的那个。这不是报错，但影响很大。常见原因是系统里装了多个 JDK，JAVA_HOME被某个安装程序改过，或者被 IDE 的设置覆盖了。处理方式是显式把JAVA_HOME设成你要的那个路径，然后重开终端再验证一次。

报错四：Linux 上Permission denied。解压时用了普通用户权限，bin/mvn没有执行位。chmod +x一下就好。另外如果是整个目录都放在/opt下，注意不要让普通用户对 Maven 安装目录有写权限，避免误改配置。

6.2 使用阶段的典型问题与处理思路

依赖冲突导致的NoSuchMethodError或ClassNotFoundException。这类问题的根因是同一个类在不同版本的 jar 里都存在，Maven 按“最近优先”的规则选了一个，但选的不是你需要的那个。排查工具是依赖树：

mvn dependency:tree -Dverbose -Dincludes=com.example:some-lib

看输出里同一个groupId:artifactId出现了几次，分别是什么版本，被谁引入的。确认之后，在pom.xml里用<exclusions>排掉不需要的那条传递依赖，或者在<dependencyManagement>里统一锁定版本。我个人的经验是，多模块项目一定要有dependencyManagement集中管版本，否则各个子模块各写各的，冲突是迟早的事。

编译乱码。表现是中文注释报警告、资源文件读出来是问号。先确认pom.xml里有<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>，再确认 IDE 的文件编码和项目编码一致。Windows 控制台如果需要看中文日志，可以临时切一下代码页，但这只影响显示，不影响源码。

本地仓库里的 jar 损坏。表现是编译时报zip file is empty或者invalid CEN header这类看着很吓人的错误。根因通常是下载中断，文件写了一半。处理方式是删掉对应坐标的整个目录，重新构建让它重下：

rm -rf ~/.m2/repository/com/example/broken-lib mvn clean package -U

构建时内存溢出。日志里出现java.lang.OutOfMemoryError，一般出现在大型多模块项目或者测试阶段。调大MAVEN_OPTS的-Xmx，从 1024m 起，不够再加。

-DskipTests和-Dmaven.test.skip=true用混了。前者只跳过测试执行，测试代码照样编译，所以测试代码里如果有编译错误，构建照样失败；后者连编译都跳过，速度快但风险是测试代码烂了你也不知道。日常赶时间用前者，特殊场景（比如测试代码依赖了缺失的库）才用后者。

6.3 一张排查速查表

关于这张表我再补一句使用心得：排查顺序应该从“环境”往“代码”走，不要反过来。很多人的习惯是看到报错就去改pom.xml，加依赖、换版本，折腾半天，最后发现是JAVA_HOME指错了。先跑mvn -v确认环境，再跑mvn dependency:tree确认依赖，最后才动配置，这个顺序能省下大量时间。

6.4 几个不讲文档但很实用的心得

第一个心得：给本地仓库做一次备份。依赖下全一次不容易，尤其是内网环境。把repository目录压缩存一份，换机器或者重装系统的时候直接解压回去，能省掉几个小时的等待。注意备份的时候不要在有构建任务跑的时候做，文件锁会导致压缩出来的是残缺的。

第二个心得：升级 Maven 版本时，先看settings.xml有没有废弃的配置项。新版本可能对某些旧配置给出警告甚至忽略，升级完先跑一次mvn -v和一次完整构建，别等到项目上线前才发现配置失效。

第三个心得：团队环境统一用同一份settings.xml模板。把本地仓库路径、镜像地址、认证方式做成模板，新人的第一步就是把模板拷到~/.m2/下改两处个人信息。这件事看起来繁琐，但能避免大量“我这里能跑你那里跑不了”的对话。

第四个心得：别迷信“重装一遍就好了”。Maven 出问题，九成是配置和网络，重装解决不了配置错误，反而会让你忘记之前改过什么。真的怀疑安装损坏，最有效的验证是把MAVEN_HOME换成一个全新解压的目录，跑一次mvn -v，如果还是同样报错，那就跟安装没关系。

第五个心得：养成看完整日志的习惯。Maven 的报错信息通常很长，前几行往往是噪音，真正的根因藏在中间某个Caused by后面。特别是依赖解析失败，日志里会明确写“哪个坐标、从哪个仓库、失败原因是什么”，认真读完通常就不用搜了。