Maven settings.xml mirrors mirrorOf 配置镜像拦截规则

mirrorof通配符仅匹配显式声明的repository id，不匹配隐式中央仓库；mirrorof 不生效于中央库，需明确写central或,!xxx；多镜像时首匹配生效；ide需手动配置settings.xml路径并启用profile。

mirrorOf 通配符匹配逻辑不按直觉工作

很多人以为 mirrorOf 写成 * 就能拦截所有仓库，实际它只匹配 <repository></repository> 的 id，且优先级由配置顺序决定。Maven 不会“覆盖”已声明的仓库，而是用镜像“替换”其请求——前提是该仓库的 id 被 mirrorOf 明确命中。

• mirrorOf *：匹配所有显式声明的 <repository></repository>（不含中央仓库默认隐式声明）
• mirrorOf external:*：匹配所有非本地文件系统仓库（推荐用于统一代理）
• mirrorOf central：仅匹配 id="central" 的仓库（常见于覆盖 Maven 中央库）
• 若多个 <mirror></mirror> 的 mirrorOf 都匹配同一仓库，**第一个生效**，后续被忽略

中央仓库被跳过？检查是否漏配 mirrorOf 值

Maven 3.0+ 默认内置了 id="central" 的仓库定义，但它是“隐式”的——你没在 pom.xml 或 settings.xml 里显式声明它，mirrorOf * 就不会触发匹配。结果就是请求直连 https://repo.maven.apache.org/maven2/，绕过你的镜像。

MiniMax开放平台

MiniMax-与用户共创智能，新一代通用大模型

下载

• 必须写 mirrorOf central 或 mirrorOf *,!jboss-public-repository-group 这类明确包含 central 的值
• 不要依赖 mirrorOf * 想当然覆盖中央库
• 验证方式：运行 mvn help:effective-pom -Dverbose，看 <repositories></repositories> 下的 id 是什么

多个镜像共存时，mirrorOf 冲突导致部分仓库失效

公司内网常同时配 Nexus、阿里云、华为云等镜像，一旦 mirrorOf 写成 * 或范围过大，就会把本该走内网私服的请求也打到公网镜像上，报 Could not transfer artifact ... from/to xxx。

• 按仓库用途拆分：用 mirrorOf internal:* 拦截内部私服，mirrorOf central,repo1 拦截公开源
• 用 ! 排除特定仓库，例如 mirrorOf *,!my-snapshots，让快照库直连内网
• 避免全量通配后又靠 <repository></repository> 的 <url></url> 覆盖——Maven 不支持这种“回退”逻辑

IDE（如 IntelliJ）不读 settings.xml 的 mirror 配置

IDE 自带的 Maven 执行器默认不加载用户 settings.xml，或加载了但未启用 active profile，导致你配好镜像后 IDE 仍连外网、下载失败、索引卡住。

• IntelliJ：File → Settings → Build → Build Tools → Maven → User settings file，手动指定路径，并勾选 “Override”
• 确认 <mirrors></mirrors> 在 <settings></settings> 根节点下，不在某个 <profile></profile> 里（除非你同时激活了该 profile）
• 命令行验证：用 mvn -X archetype:generate 看 debug 日志中 Using mirror 是否出现预期地址