构建与依赖 / 系统课时

镜像与私有仓库配置

镜像与私有仓库配置

Maven 的镜像不是简单“换一个下载地址”,而是先用 mirrorOf 判断某个仓库是否应被替换,再把请求转到镜像 URL。正确配置后,可以让中央仓库和外部仓库统一经过 Nexus、Artifactory 等私服代理,同时保留少数必须直连的仓库。

学习目标

  • 理解 mirrorOf 的常见匹配写法及排除规则。
  • 配置仓库镜像,并让镜像认证与 server.id 正确对应。
  • 用 Effective Settings 检查镜像规则是否被 Maven 读取。

用 mirrorOf 精确控制匹配范围

mirrorOf 匹配的是仓库 ID 或仓库类别,不是域名。下面几种写法最常用,选择时先明确“哪些仓库必须经过私服,哪些必须保留直连”。

mirrorOf 实际含义 适用场景
* 匹配全部仓库 公司只允许经过一个统一仓库组
central 只匹配 ID 为 central 的仓库 只替换 Maven Central
external:* 匹配除本机与 file: 仓库外的外部仓库 统一代理网络仓库,同时保留本地测试仓库
external:*,!direct-releases 匹配外部仓库,但排除 direct-releases 大多数走私服,单个仓库保持直连
repo-a,repo-b 只匹配列出的仓库 ID 精确控制少量仓库

排除项用 !,多个规则用英文逗号分隔。不要在 ID 周围随意加入空格。若同时存在精确 ID 镜像和通配规则,精确 ID 匹配优先;需要多个通配规则时,应把更具体的规则放在前面,避免声明顺序造成意外命中。

配置统一镜像与认证

下面示例把所有外部网络仓库统一转到公司仓库组 corp-public。镜像真正发起 HTTP 请求时使用的是镜像自己的 ID,所以 <servers> 中的认证 ID 必须写 corp-public,而不是 central。

xml
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <mirror>
      <id>corp-public</id>
      <name>Corporate Maven public group</name>
      <url>https://repo.example.com/repository/maven-public/</url>
      <mirrorOf>external:*</mirrorOf>
    </mirror>
  </mirrors>

  <servers>
    <server>
      <id>corp-public</id>
      <username>${env.REPO_USER}</username>
      <password>${env.REPO_PASSWORD}</password>
    </server>
  </servers>
</settings>

Maven 镜像匹配与认证关系示意图

如果公司私服的 maven-public 已聚合 Central、第三方代理和内部 Release 仓库,mirrorOf 用 * 往往最简单;若仍需要访问本机 file: 仓库或 localhost 测试服务,使用 external:* 更合适。需要直连某个远程仓库时,再用 !仓库ID 明确排除。

验证镜像规则已经被读取

先让 Maven 生成合并后的 Effective Settings,再用固定字符串搜索 mirrorOf。下面命令不会打印账号或密码,只验证规则存在。

bash
mvn -q help:effective-settings -Doutput=effective-settings.xml && grep -Fq '<mirrorOf>external:*</mirrorOf>' effective-settings.xml && grep -Fq '<id>corp-public</id>' effective-settings.xml && printf 'mirror rule loaded\n'

预期输出:

text
mirror rule loaded

这一步只能证明配置被读取,不能证明私服本身可用。随后应在一个真实项目中做一次缺失依赖解析;若镜像可达且权限正确,请求会转向 https://repo.example.com/repository/maven-public/。若返回 401,先查 server.id 与镜像 ID;若返回 404,则检查私服仓库组是否真的代理了目标仓库和对应制品。

修正最容易踩坑的匹配方式

最常见的错误是把 <mirrorOf>central</mirrorOf> 当成“所有依赖都走私服”。它只替换 ID 为 central 的仓库,POM 或 Profile 中额外声明的其他仓库仍可能直连。若公司策略要求统一出口,应改成 * 或 external:*,并确认私服能代理所需来源。

另一个错误是配置多个 <mirror> 指向同一个仓库并期待 Maven 自动轮询或故障转移。Maven 镜像用于仓库替换,不是负载均衡器;同一仓库最终只会选定一个匹配镜像。高可用应在私服、反向代理或 DNS 层实现,而不是堆叠多个 mirrorOf 规则。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

镜像与私有仓库配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通