maven为什么只连接第一个mirror，用错场景反而更麻烦

你在 settings.xml 里配了多个 mirror，指望 A 仓库挂了自动走 B，结果 Maven 永远只连第一个，后面的镜像像不存在一样。理解 maven mirror 的匹配机制就知道：一个 <mirror> 只能映射一组仓库，Maven 按配置顺序选中第一个能匹配的就停止。用错场景反而更麻烦——比如把全部仓库都镜像到同一个私有库，一旦它挂了，所有构建一起失败。本文讲清匹配机制、常见误用和正确写法，并给出配置、验证与失败排查的完整步骤，让你不再被"我以为有备胎"坑到。

maven 为什么只连接第一个 mirror 的匹配机制

先看结论

maven mirror 只会应用第一个匹配到的 <mirror>，后面的直接被忽略，不是按顺序重试。
mirrorOf 写 * 会把所有仓库都转到这一个镜像，等于制造了单点，私有库挂掉全线构建失败。
多个镜像想互为主备，要按仓库分别用 mirrorOf 精确匹配，而不是堆多个 *。
排查时优先看 mvn help:effective-settings 输出的实际生效配置，别只盯着手写的那段。
记住"命中即停"四个字，就能解释绝大多数 maven mirror 只连第一个的怪现象。

一、mirror 到底是什么

mirror 是"仓库的镜像"，用来把对某个远程仓库的请求重定向到另一个地址。常见用法是把中央仓库 central 指向公司私服，加速下载。根据 Maven 官方文档，mirror 的匹配只看 mirrorOf 与仓库 id 的关系，和写在什么位置无关。

<mirror>
  <id>nexus</id>
  <mirrorOf>central</mirrorOf>
  <url>https://nexus.example.com/repo</url>
</mirror>

这里 mirrorOf 是 central，只拦截中央仓库。Maven 依赖解析时，遇到要访问 central 的请求，就转去 nexus。这正是 maven mirror 最基础也最常被误解的地方，也是理解后续行为的入口。关于 Maven 的更多配置项与速查，可查 Maven 教程。

settings.xml 中多个 mirror 的匹配顺序

注意 mirror 和 repository 是两回事：repository 定义"去哪下"，mirror 定义"把去 A 的请求拐到 B"。很多人把它们混在一起，才会以为多写几个 mirror 就等于多几个 repository 备选，其实完全不是一回事。理解 maven mirror 的边界，先要把这两个概念拆开。

二、为什么只连第一个

Maven 解析某个仓库时，会遍历所有 mirror，选出第一个 mirrorOf 匹配该仓库的镜像并应用，之后就不再看后面的了。所以即便你配了第二个、第三个，只要第一个已经命中，它们永远轮不到。

这也是 maven 为什么只连接第一个 mirror 的根本原因：它不是"按顺序尝试直到成功"，而是"命中即停"。把它理解成路由表的首次匹配，就不容易踩坑。检查实际生效配置时，别只信手写的顺序，因为 maven mirror 的优先级来自匹配顺序而非你直觉里的"备胎列表"。Java 项目的构建链路和 Maven 私服常配合使用，Java 教程里的相关内容有助于你排错。还有一个常见误解：mirror 是按"请求时匹配"工作的，不是"配置时绑定"。也就是说，解析某个具体依赖时，Maven 才去看哪个 mirror 的 mirrorOf 命中了它所在的仓库，命中第一个就定下来。这进一步说明，所谓"第二个镜像兜底"在命中即停的规则下根本不会发生。

三、用错场景反而更麻烦

最典型的误用是把 mirrorOf 写成 *：

<mirror>
  <id>all</id>
  <mirrorOf>*</mirrorOf>
  <url>https://one.example.com</url>
</mirror>

这样所有仓库（central、公司的、第三方的）全被转到 one.example.com。一旦这个地址不可用，Maven 依赖下载会整体失败，而你以为"我还有第二个镜像仓库兜底"——其实它根本没机会生效。构建加速没拿到，反而制造了单点故障。镜像仓库本该是冗余保障，用错反而变成唯一瓶颈。要核对每个 mirrorOf 到底拦了哪些仓库，可随时翻 Maven 速查手册，对照官方的通配符写法避免踩坑。

这里还有一层：maven mirror 的匹配只看 mirrorOf 与仓库 id 的关系，不看仓库内容、不看网络是否可达。所以即便第二个镜像更快更稳，只要第一个先命中，它永远轮不到。把"主备"寄托在多个 * 上，本质上是误解了匹配规则。

四、正确的配置写法与验证

想让多个镜像互为主备，应该按仓库精确分组，而不是用通配：

<mirror>
  <id>central-nexus</id>
  <mirrorOf>central</mirrorOf>
  <url>https://nexus.example.com/central</url>
</mirror>
<mirror>
  <id>thirdparty-nexus</id>
  <mirrorOf>thirdparty-repo</mirrorOf>
  <url>https://nexus.example.com/thirdparty</url>
</mirror>

不同仓库各自有镜像，互不影响；某个镜像挂了，只影响它对应的那部分依赖。配置完后，运行 mvn help:effective-settings 验证实际生效结果，预期会看到合并后的真实镜像映射，而不是你手写的片段。若构建失败，先检查是不是 mirrorOf 重叠导致请求被错误重定向，再修复对应段落。

构建时各仓库命中不同镜像的耗时对比

实际项目里，建议把 mirror 配置和项目本身解耦：mirror 放用户级 settings.xml，仓库声明放 pom.xml，这样换机器、换人协作时不会把私服地址写死在工程里。验证是否解耦成功，同样用 mvn help:effective-settings 一眼看穿。别迷信"多配几个 mirror 更稳"，数量多不等于容错高，规则写对才关键。

总结

maven 为什么只连接第一个 mirror，本质是"首次匹配即停止"的路由规则。把 maven mirror 当成匹配表而不是重试链，就能避开大多数坑。mirrorOf 慎用 *，按仓库分组最稳；排查永远先看 effective-settings 的实际生效结果，验证通过再提交配置。真遇到镜像挂了，正确做法是换 mirrorOf 指向的地址或临时注释该 mirror，而不是再叠一个永远轮不到的镜像。

延伸学习

想把 Maven 吃透，可以顺着这条线：

系统学构建工具，项目管理利器：Maven精讲；
遇到依赖打架时看 Maven依赖冲突解决；
多仓库场景参考 Java Maven 构建项目利器。

常见问题

Q：mirrorOf 写成 `*` 后第二个 mirror 真的完全不生效吗？

A：对，只要第一个 * 已经命中，后续 mirror 就不会被考虑。Maven 不会在第一个镜像失败时自动跳到下一个，所以 * 加多镜像并没有主备效果，反而把多个仓库都押在同一台机器上。

Q：怎么确认实际生效的是哪份配置？

A：运行 mvn help:effective-settings，它会把 settings.xml、全局配置、默认项合并后的真实结果打印出来。手写的那段和实际生效的可能不一样，以它为权威来源检查与验证。

Q：公司私服和中央仓库都要镜像，怎么不冲突？

A：用 mirrorOf 分别指名，比如一个 central 一个具体仓库 id，各自指向对应地址。只要 mirrorOf 不重叠，它们就能并存且互不影响。若仍失败，优先排查 id 拼写与网络连通性再修复。