Maven Site 插件默认绕过 settings.xml 中配置的镜像和仓库，直接访问中央仓库（repo.maven.apache.org），导致构建失败；本文详解如何通过 <mirrorOf>*</mirrorOf> 全局镜像配置强制所有请求（含 site 插件）路由至私有仓库。
maven site 插件默认绕过 `settings.xml` 中配置的镜像和仓库，直接访问中央仓库（repo.maven.apache.org），导致构建失败；本文详解如何通过 `
在 Maven 构建生命周期中，mvn clean install 等常规命令能正确读取 ~/.m2/settings.xml 中定义的私有仓库（如 Nexus 或 Artifactory），但 mvn site（或 mvn site:site）却常抛出类似错误：
Failed to transfer file: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-site-plugin/3.7.1/maven-site-plugin-3.7.1.jar
这表明 Site 插件在解析其自身依赖（如 maven-site-plugin、maven-project-info-reports-plugin 及其传递依赖）时，未遵循用户配置的 <repositories> 或 <mirrors> 规则，而是回退到硬编码的中央仓库地址。
根本原因在于：Maven 的 site 生命周期由 maven-site-plugin 驱动，而该插件在初始化阶段需动态解析自身及报告插件的依赖——此时 Maven 尚未完全加载项目级 POM 中的仓库配置，且插件解析阶段优先使用全局 settings.xml 中的 <mirrors>，但仅当 <mirrorOf> 明确匹配目标仓库 ID 时才生效。若你的私有仓库未被显式镜像，Maven 便会尝试直连 central（即 repo.maven.apache.org）。
✅ 正确解法：在 ~/.m2/settings.xml 的 <mirrors> 节点中添加一条 通配符镜像（wildcard mirror），强制将所有仓库请求（包括 central）重定向至你的私有仓库：
<settings>
<mirrors>
<!-- 关键配置：将所有仓库请求（*）镜像到私有仓库 -->
<mirror>
<id>private-repo-mirror</id>
<url>https://your-company-nexus.example.com/repository/maven-public/</url>
<mirrorOf>*</mirrorOf>
<name>Private Repository Mirror for All Repos</name>
</mirror>
</mirrors>
</settings>⚠️ 注意事项：
- <mirrorOf>*</mirrorOf> 是唯一能覆盖 central 的写法；<mirrorOf>central</mirrorOf> 或 <mirrorOf>*,!some-other-id</mirrorOf> 均不可靠，因 site 插件可能使用非标准仓库 ID。
- 确保 <url> 指向的是支持代理/转发的私有仓库地址（如 Nexus 的 maven-public 仓库组），它应能透明代理对 repo.maven.apache.org 的请求，而非仅托管已缓存的构件。
- 不要试图在 pom.xml 中为 maven-site-plugin 显式声明 <dependencies> 来“预加载”依赖——这不仅维护成本高、易遗漏，还违背依赖管理原则，且无法解决插件元数据（如 plugin.xml）的解析问题。
- 若使用 Maven 3.8.1+，注意 https 强制策略：确保私有仓库 URL 使用 https，且证书受信任；否则会触发 SSL 握手失败。
验证是否生效：执行 mvn site -X | grep "Downloading from"，输出中所有 Downloading from 行的仓库 ID 应均为 private-repo-mirror，且 URL 均指向你的私有地址，不再出现 central 或 repo.maven.apache.org。
总结：Site 插件的仓库行为差异源于 Maven 插件解析机制的特殊性，而非配置错误。通过 <mirrorOf>*</mirrorOf> 实现全局请求劫持，是最简洁、可靠且符合 Maven 设计哲学的解决方案。
