1. 依赖下载慢这件事，到底卡在哪

做 Java 项目的人大概都经历过这种场景：新建一个工程，pom.xml刚写完，点一下刷新，进度条在Downloading from central那里一动不动，泡杯咖啡回来还在转，最后干脆给你抛个Could not transfer artifact或者Read timed out。这不是你的代码有问题，也不是网络断了，而是 Maven 默认走的中央仓库节点在境外，物理距离加上链路抖动，下载一个几十 KB 的 jar 都可能耗掉十几秒，依赖一多，构建时间直接失控。

这篇内容聊的就是怎么用国内公共镜像把 Maven 依赖下载速度拉起来，核心手段是配置阿里云和华为云的 Maven 镜像仓库。说白了，就是把 Maven 默认去境外中央仓库取包的行为，改成去国内的镜像节点取包，镜像节点会定期同步中央仓库的内容，你请求的 jar、pom、元数据它本地就有，响应时间从几百毫秒降到几十毫秒，批量拉依赖时的差距非常明显。

适合谁看？刚接触 Maven 的新手可以照着配一遍，解决“项目跑不起来”的入门障碍；有一定经验的开发者可以看看镜像配置的优先级逻辑、settings.xml和pom.xml两种配置方式的取舍、以及多镜像并存时怎么避免踩坑。我下面会把配置原理、实操步骤、参数细节和常见故障排查都摊开讲，尽量做到你读完就能直接抄作业，同时知道每一步为什么这么写。

需要先明确一个概念：镜像（mirror）不是仓库（repository）的替代品，而是仓库的拦截层。Maven 在解析依赖时，会先看当前仓库有没有配置对应的 mirror，如果有，就把对原仓库的请求重定向到 mirror 指向的地址。理解这一点，后面配置mirrorOf参数时就不会迷糊。

2. 镜像加速的整体思路与方案选型

2.1 为什么是镜像而不是换仓库地址

很多人第一反应是直接把pom.xml里的仓库地址改成国内地址，这个思路方向对，但不够优雅。原因在于：项目里可能引用了多个仓库（中央仓库、某个开源组织的仓库、公司私服），你逐个改地址工作量大且容易漏；更麻烦的是，团队协作时每个人的本地配置不一样，改pom.xml会把个人环境差异带进版本库，污染构建配置。

镜像机制解决的正是这个问题。它在 Maven 的配置层做一次统一拦截，所有对指定仓库的请求都走镜像地址，项目文件一个字不用动。配置写在settings.xml里，属于用户级或全局级设置，跟项目解耦，换项目照样生效。这就是我推荐用镜像而不是改仓库地址的核心理由：配置与项目分离，一次配置全局受益。

2.2 阿里云与华为云镜像的定位差异

国内可用的 Maven 公共镜像不止一家，阿里云和华为云是使用最广的两个。它们都能代理 Maven 中央仓库，但在实际使用中有一些细微差别，我整理成表格方便对照：

两家都能满足绝大多数项目的依赖拉取需求。我的实际做法是主用阿里云，华为云作为备用，在settings.xml里配置多个 mirror 时要注意，Maven 对同一个mirrorOf匹配规则只会生效第一个，所以备用镜像不是简单并列写两个就行，得靠不同的匹配规则或者手动切换。这一点在后面的排查章节会详细说。

2.3 配置放在 settings.xml 还是 pom.xml

这是新手最容易纠结的点。结论先给：加速用途的镜像配置，一律放settings.xml。理由有三条。

第一，settings.xml是 Maven 的运行级配置，优先级高于pom.xml中的仓库声明，镜像拦截在更底层生效，覆盖面更全。第二，settings.xml分用户级（~/.m2/settings.xml）和全局级（Maven 安装目录下conf/settings.xml），用户级只影响自己，不会干扰团队其他人。第三，pom.xml里的<repositories>是项目依赖来源声明，语义上是“这个项目需要从哪些仓库找包”，把加速镜像塞进去属于语义错位，而且一旦项目被别的团队引用，你的镜像配置会跟着传播出去，不合适。

提示：如果你在公司里需要统一给团队配置镜像，改全局级settings.xml或者用配置管理工具下发用户级配置都行，但不要改项目pom.xml。

3. 核心配置细节与参数拆解

3.1 settings.xml 的结构与镜像节点位置

settings.xml的根节点是<settings>，镜像配置写在<mirrors>下面，每个镜像是一个<mirror>节点。一个典型的镜像节点包含四个子元素：

• <id>：镜像的唯一标识，自定义字符串，不能和其他 mirror 的 id 重复。
• <name>：给人看的名称，随便写，不影响功能。
• <url>：镜像仓库的实际地址，这是核心。
• <mirrorOf>：匹配规则，决定这个镜像拦截哪些仓库的请求。

这四个元素里，id和mirrorOf是最容易出问题的。id重复会导致 Maven 启动时报配置错误；mirrorOf写错会导致镜像不生效或者拦截了不该拦截的仓库。下面重点讲mirrorOf。

3.2 mirrorOf 匹配规则详解

mirrorOf的值决定了镜像的拦截范围，常见写法有这几种：

新手最常用的是*，一行搞定，所有依赖请求都走镜像。但这里有个坑：如果你公司有内部私服，*会把私服请求也重定向到公共镜像，导致内部构件拉不到。正确写法是*,!私服id，用感叹号排除。这个细节很多教程不提，但实际工作中几乎必踩。

注意：mirrorOf的排除语法是*,!repoId，感叹号后面跟的是仓库的 id，不是 url，也不是 name。写错了不报错，但排除不生效，排查起来很费劲。

3.3 阿里云镜像的完整配置写法

把下面这段贴进settings.xml的<mirrors>节点内即可。我加了注释说明每个字段的意图：

<mirror> <!-- 唯一标识，自定义，建议语义化命名 --> <id>aliyun-public</id> <!-- 名称，仅用于展示 --> <name>Aliyun Public Mirror</name> <!-- 阿里云公共仓库地址，代理了中央仓库及常用生态仓库 --> <url>https://maven.aliyun.com/repository/public</url> <!-- 拦截所有仓库请求；若有私服，改为 *,!私服id --> <mirrorOf>*</mirrorOf> </mirror>

阿里云的public仓库是一个聚合仓库，它背后合并了中央仓库、Spring 仓库、Google 仓库等多个来源，所以配一个public基本能覆盖大部分依赖。如果你需要更精细地控制，阿里云还提供central、spring、google、gradle-plugin等独立地址，可以按需配置多个 mirror，但要注意mirrorOf的匹配不能冲突。

3.4 华为云镜像的配置写法

华为云的配置结构完全一样，只是 url 不同：

<mirror> <id>huaweicloud</id> <name>Huawei Cloud Mirror</name> <url>https://repo.huaweicloud.com/repository/maven/</url> <mirrorOf>central</mirrorOf> </mirror>

这里我故意把mirrorOf写成central而不是*，原因是当你想同时保留阿里云做主镜像时，两个 mirror 的mirrorOf不能都写*，否则只有一个生效。把华为云限定为只拦截central，再配合阿里云的全量拦截，实际效果是阿里云优先，华为云作为中央仓库的补充——不过更稳妥的做法还是只启用一个主镜像，备用镜像在需要时手动切换，避免匹配规则互相干扰。

3.5 本地仓库路径的连带优化

镜像配好只是第一步，依赖下载下来后存在本地仓库，默认路径是~/.m2/repository。如果你的系统盘空间紧张，或者想把仓库放到更快的磁盘上，可以在settings.xml里改<localRepository>：

<localRepository>/data/maven-repo</localRepository>

这个改动和镜像加速是配套的：镜像解决“下载快”，本地仓库路径解决“存得下、读得快”。我见过不少人在系统盘塞满后才想起来改这个，其实一开始就规划好更省事。改完路径后，旧仓库里的依赖不会自动迁移，需要手动拷贝或者重新下载，所以建议在项目初期就定好路径。

4. 实操过程：从零配置到验证生效

4.1 定位并备份 settings.xml

第一步是找到你的settings.xml。用户级配置在~/.m2/settings.xml（Windows 是C:\Users\用户名\.m2\settings.xml），全局级在 Maven 安装目录的conf/settings.xml。如果用户级文件不存在，可以从全局级复制一份过来，或者新建一个。

动手改之前先备份，这是铁律：

cp ~/.m2/settings.xml ~/.m2/settings.xml.bak

备份的意义在于，配置写错导致 Maven 起不来时，能一键回滚，不用凭记忆恢复。我踩过一次坑，mirrorOf里多打了个空格，Maven 直接报Non-parseable settings，当时没备份，只能重装配置，浪费了半小时。

4.2 写入镜像配置

用任意文本编辑器打开settings.xml，找到<mirrors>节点。如果节点存在但被注释了，把注释去掉；如果不存在，在<settings>根节点下补一个。把 3.3 节的阿里云配置贴进去，保存。

这里有个细节：settings.xml是 XML 文件，对格式敏感。粘贴时注意不要破坏原有的缩进和闭合标签，尤其是<mirrors>和</mirrors>必须成对。改完后可以用xmllint --noout settings.xml做一次语法校验，没有输出就说明格式没问题。

4.3 清理本地缓存并触发重新下载

镜像配置生效后，之前下载失败的依赖可能留下了.lastUpdated标记文件，Maven 看到这些文件会认为“这个依赖下载失败过”，从而跳过重试。所以配置完成后，建议清理一下相关缓存：

# 删除所有下载失败标记 find ~/.m2/repository -name "*.lastUpdated" -delete

如果某个依赖反复下载失败，可以直接删掉它对应的目录，强制 Maven 重新拉取。清理完执行一次构建：

mvn clean compile -U

-U参数强制更新快照依赖和检查远程仓库，配合镜像配置能确保请求走的是新地址。观察控制台输出，如果看到Downloading from aliyun-public: https://maven.aliyun.com/...这样的日志，说明镜像已经生效。

4.4 用依赖树验证下载来源

想确认某个依赖到底从哪个仓库下载的，可以用dependency:tree配合调试日志：

mvn dependency:tree -X | grep "Downloading from"

-X打开调试模式，输出里会明确标注每个构件的下载来源。如果来源显示的是镜像 id 对应的地址，配置就是成功的。这个方法比看构建速度更可靠，因为速度受网络波动影响，而日志是确定的。

4.5 速度对比的实测方法

想量化加速效果，可以做个简单对比：清空本地仓库中某个较大依赖的目录，分别在配置镜像前后执行下载，记录耗时。我实测过一个约 8MB 的常用工具包，直连中央仓库平均耗时 40 秒以上，走阿里云镜像稳定在 3 到 5 秒，差距接近一个数量级。当然这个数据受网络环境影响很大，你的结果可能不同，但趋势是一致的。

提示：做速度对比时，记得每次测试前清掉对应的本地缓存，否则第二次直接命中本地仓库，测出来的是 0 秒，没有参考意义。

5. 常见问题与排查技巧实录

5.1 配置后依然走中央仓库

这是最高频的问题。现象是日志里还是Downloading from central，镜像没生效。排查顺序如下：

第一，确认改的是哪个settings.xml。Maven 实际加载的是用户级还是全局级，可以用mvn help:effective-settings查看，输出里会显示当前生效的镜像配置。如果输出里没有你配的镜像，说明改错文件了。

第二，检查mirrorOf是否匹配。如果项目pom.xml里自定义了仓库 id，而你的mirrorOf写的是central，那自定义仓库的请求不会被拦截。改成*或者把自定义 id 加进去。

第三，检查是否有多个 mirror 冲突。同一个mirrorOf匹配规则下，只有第一个 mirror 生效，后面的被忽略。用effective-settings看清楚哪个排在前。

5.2 报错 Non-parseable settings

这个错误说明settings.xml的 XML 格式坏了，常见原因是标签没闭合、特殊字符没转义、或者粘贴时混入了不可见字符。解决办法是用xmllint定位错误行号，或者直接拿备份文件对比。url 里的&符号必须写成&，虽然镜像地址一般不带这个符号，但配置其他内容时容易忽略。

5.3 依赖能下载但构建仍失败

镜像只负责“把包拉下来”，包拉下来之后构建失败，问题就不在镜像了。常见情况是依赖版本冲突、缺少传递依赖、或者拉下来的包不完整。可以先执行mvn dependency:resolve看依赖解析是否完整，再用dependency:tree排查冲突。如果怀疑包损坏，删掉对应目录重新下载。

5.4 公司私服构件拉不到

这就是 3.2 节提到的*通配符误伤问题。公司私服的请求被重定向到公共镜像，公共镜像上没有内部构件，自然拉不到。解决办法是把mirrorOf改成*,!私服id，让私服请求直连。私服 id 在pom.xml或settings.xml的<repositories>里能找到，通常是公司自定义的字符串。

5.5 镜像地址访问不通

有时候是镜像服务本身临时不可用，或者你的网络环境对特定域名有限制。排查方法是直接用浏览器或curl访问镜像 url，看能否返回内容：

curl -I https://maven.aliyun.com/repository/public/

返回 200 说明地址可达，问题在 Maven 配置；返回超时或 4xx，说明是网络或服务端问题，可以临时切换到华为云镜像验证。这也是我建议保留备用镜像配置的原因，主镜像出问题时能快速切换。

5.6 常见问题速查表

6. 几个我踩过坑才明白的经验

配置镜像这件事看起来简单，但细节上的坑不少，分享几条实际经验。

第一条，别迷信“配了就快”。镜像生效的前提是请求真的走了镜像，很多人配完不验证，以为快了，其实日志里还是 central，只是那次网络恰好没抖。养成用-X看下载来源的习惯，比凭感觉靠谱。

第二条，mirrorOf的排除语法要记牢。*,!repoId这个写法我用了很多年，但每次给新人讲，总有人写成*,!repoName或者*!repoId，前者排除不生效，后者直接语法错误。记住感叹号紧跟逗号，后面跟 id。

第三条，本地仓库和镜像要一起规划。只配镜像不改仓库路径，依赖越拉越多，系统盘迟早告急；只改路径不配镜像，下载慢的问题还在。两件事一起做，一次到位。

第四条，备用镜像不是并列写两个。Maven 的 mirror 匹配是“首个命中即生效”，两个mirrorOf都写*的镜像，第二个永远不会被用到。想要备用效果，要么用不同的匹配规则错开，要么在出问题时手动改配置切换。我个人的做法是主镜像配*，备用镜像的配置写在注释里，需要时取消注释、注释掉主镜像，切换成本很低。

第五条，团队协作时统一配置来源。如果团队里有人用阿里云、有人用华为云、有人没配，构建结果可能因为依赖来源不同而出现细微差异。稳妥的做法是团队约定统一的镜像配置，通过文档或配置下发的方式保证一致，减少“在我机器上是好的”这类问题。

这套配置本身不复杂，真正花时间的是理解mirrorOf的匹配逻辑和排查“为什么没生效”。把这两块吃透，后面换任何镜像源都是改个 url 的事。