构建与依赖 / 系统课时
镜像与私有仓库配置
镜像与私有仓库配置
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 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-public 已聚合 Central、第三方代理和内部 Release 仓库,mirrorOf 用 * 往往最简单;若仍需要访问本机 file: 仓库或 localhost 测试服务,使用 external:* 更合适。需要直连某个远程仓库时,再用 !仓库ID 明确排除。
验证镜像规则已经被读取
先让 Maven 生成合并后的 Effective Settings,再用固定字符串搜索 mirrorOf。下面命令不会打印账号或密码,只验证规则存在。
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'预期输出:
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 规则。