在 Maven 中，repository 和 mirror 都与依赖拉取相关，但它们的作用机制和优先级不同。下面将详细介绍两者的概念、生效规则及实际应用场景：

一、repository 和 mirror 的基本概念

1. repository（仓库）

  • 定义：Maven 用于存储和获取依赖项、插件、项目构建结果的远程服务器。

  • 作用：指定 Maven 从哪些远程仓库下载依赖，例如 Maven 中央仓库（central）、阿里云仓库等。

  • 默认配置：

    • 无自定义配置时：Maven 默认会访问中央仓库（ID 为central，URL 为https://repo.maven.apache.org/maven2）。
    • 自定义 repository 覆盖默认行为：当在settings.xml或pom.xml中显式声明repository时，会覆盖 Maven 的默认仓库配置，即不再自动访问中央仓库。

2. mirror（镜像）

  • 定义：用于替代某个仓库的服务器，相当于仓库的 “副本”。

  • 作用：当配置镜像后，Maven 会优先从镜像服务器拉取依赖，而非原始仓库。

    当 mirror 配置中的 mirrorOf 与某个 repository 匹配时，Maven 会把对该 repository 的请求重定向到 mirror 所指定的 url 地址去下载资源。

  • 核心原则：mirror 必须关联到已声明的 repository 仓库 ID 才能生效，否则视为无效配置。若需通过镜像访问中央仓库，需先在 repository 中声明中央仓库或使用通配符镜像。

  • 典型场景：国内用户常配置阿里云镜像（https://maven.aliyun.com/repository/public）以加速下载。

二、生效规则：mirror 优先级高于 repository

1. 镜像的匹配机制

当在 settings.xml 中配置 mirror 时，需通过 mirrorOf 字段指定要替代的仓库：

  • 示例配置：
1
2
3
4
5
6
<mirror>
  <id>aliyun-maven</id>
  <mirrorOf>central</mirrorOf>
  <name>Aliyun Maven</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>
  • mirrorOf的取值：
    • central：替代中央仓库。
    • *：替代所有仓库（包括自定义仓库）。
    • 仓库 id：仅替代指定 id 的仓库（如 mirrorOf>my-repo</mirrorOf>）。

2. 生效优先级

  • 当 mirror 匹配仓库时：Maven 会完全使用镜像的 url 地址，忽略原始仓库的配置。

  • 当 mirror 不匹配仓库时：Maven 仍会从 repository 配置的仓库拉取依赖。

三、实际应用场景示例

1. 场景一：配置中央仓库的镜像

  • 需求：加速中央仓库依赖的下载。

  • 配置：

1
2
3
4
5
6
7
8
<!-- settings.xml 中添加 -->
<mirrors>
  <mirror>
    <id>aliyun-central</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/central</url>
  </mirror>
</mirrors>
  • 生效结果：所有对中央仓库（central）的请求都会转向阿里云镜像，repository 中配置的中央仓库被覆盖。

2. 场景二：同时使用自定义仓库和镜像

  • 需求：项目需要从自定义仓库 my-repo 拉取依赖，同时为中央仓库配置镜像。

  • 配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!-- settings.xml 中的 mirror 配置 -->
<mirror>
  <id>aliyun-central</id>
  <mirrorOf>central</mirrorOf>
  <url>https://maven.aliyun.com/repository/central</url>
</mirror>

<!-- pom.xml 中的 repository 配置 -->
<repositories>
  <repository>
    <id>my-repo</id>
    <url>https://my-repo.com/maven</url>
  </repository>
</repositories>
  • 生效结果：
    • 中央仓库依赖从阿里云镜像拉取。
    • my-repo 仓库的依赖从自定义 url 拉取，不受镜像影响。

四、总结：mirror 覆盖 repository 的条件

条件 结果
mirrorOf 匹配仓库 id 使用 mirror 的 url，忽略 repository
mirrorOf 未匹配仓库 repository 正常生效
mirrorOf 设置为 * 所有 repository 都被镜像替代

最佳实践

  • 如需加速公共仓库（如中央仓库），优先在 settings.xml 中配置镜像。

  • 自定义私有仓库通常不配置镜像，直接在 pom.xml 或 settings.xml 中声明 repository。

  • 避免将 mirrorOf 设置为 *，以免意外覆盖私有仓库的配置。

通过合理配置 mirror 和 repository，可以在保证依赖拉取准确性的同时，优化下载速度和稳定性。