Maven 构建排查：settings.xml、镜像、代理与证书

• 1. 找到真正生效的 settings.xml
• 2. 镜像：mirrorOf 写法决定覆盖范围
• 3. 代理设置
• 4. 证书：PKIX 报错
• 5. 仓库认证：server id 必须对上
• 6. 清理失败缓存

Maven 构建报 Could not transfer artifact、PKIX path building failed，或者私服 401，看起来是三种问题，其实都能沿着 settings.xml 一条线查清楚。

§1. 找到真正生效的 settings.xml

Maven 会合并两份配置：

• 全局：$MAVEN_HOME/conf/settings.xml
• 用户：~/.m2/settings.xml

用下面的命令看合并后的结果：

mvn help:effective-settings

§2. 镜像：mirrorOf 写法决定覆盖范围

<mirrors>
  <mirror>
    <id>corp-mirror</id>
    <mirrorOf>*,!internal-snapshots</mirrorOf>
    <url>https://repo.example.com/maven2</url>
  </mirror>
</mirrors>

* 会拦截所有仓库，!id 用来排除某个仓库。很多“私服里明明有包却下载不到“的问题，就是镜像把私服请求也拦走了。

§3. 代理设置

Maven 不读 HTTPS_PROXY 环境变量，要在 settings.xml 中声明：

<proxies>
  <proxy>
    <id>local</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>127.0.0.1</host>
    <port>7890</port>
    <nonProxyHosts>localhost|*.example.com</nonProxyHosts>
  </proxy>
</proxies>

注意 nonProxyHosts 用竖线分隔，内网私服记得加进去。

§4. 证书：PKIX 报错

公司网络做 TLS 检查时，JDK 不信任中间证书。把根证书导入一个单独的 truststore，再通过 MAVEN_OPTS 指定：

keytool -importcert -alias corp -file corp-root.cer -keystore ~/.m2/corp.jks
export MAVEN_OPTS="-Djavax.net.ssl.trustStore=$HOME/.m2/corp.jks"

§5. 仓库认证：server id 必须对上

<servers> 里的 <id> 要和 pom 或 mirror 里的 id 完全一致，否则凭据不会被带上，结果就是 401。

§6. 清理失败缓存

下载失败会留下 *.lastUpdated 文件，导致之后一直不重试：

find ~/.m2/repository -name "*.lastUpdated" -delete
mvn -U clean package

完整的分场景排查可以看 Maven：代理、镜像与仓库认证。

由 Roxi 背后的小团队撰写。