Maven Site 插件默认绕过 settings.xml 中配置的镜像和仓库，直接访问中央仓库（repo.maven.apache.org），导致构建失败；本文详解如何通过 * 全局镜像配置强制所有请求（含 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 及其传递依赖）时，未遵循用户配置的
根本原因在于：Maven 的 site 生命周期由 maven-site-plugin 驱动，而该插件在初始化阶段需动态解析自身及报告插件的依赖——此时 Maven 尚未完全加载项目级 POM 中的仓库配置，且插件解析阶段优先使用全局 settings.xml 中的
✅ 正确解法：在 ~/.m2/settings.xml 的
<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>
⚠️ 注意事项：
-
* 是唯一能覆盖 central 的写法；central 或*,!some-other-id 均不可靠，因 site 插件可能使用非标准仓库 ID。 - 确保
指向的是支持代理/转发的私有仓库地址（如 Nexus 的 maven-public 仓库组），它应能透明代理对 repo.maven.apache.org 的请求，而非仅托管已缓存的构件。 - 不要试图在 pom.xml 中为 maven-site-plugin 显式声明
来“预加载”依赖——这不仅维护成本高、易遗漏，还违背依赖管理原则，且无法解决插件元数据（如 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 插件解析机制的特殊性，而非配置错误。通过
