Maven 构建时 SSL 证书验证失败的解决方案

本文介绍如何解决 maven 3.9+ 因启用默认 native https 传输层而导致的 pkix 证书路径验证失败问题（如 `pkix path building failed`），提供安全、临时和长期三种应对策略。

从 Maven 3.9.0 版本开始，Apache Maven 将默认的 HTTP 传输实现由 httpclient 切换为 native（基于 JDK 内置 java.net.http.HttpClient）。该变更提升了性能与兼容性，但也带来了更严格的 TLS/SSL 验证行为——尤其在企业环境（如使用代理、中间人证书、自定义 CA 或 JDK 信任库未同步更新）下，容易触发如下典型错误：

Non-resolvable import POM: Could not transfer artifact org.junit:junit-bom:pom:5.6.2 
from/to central (https://repo.maven.apache.org/maven2): 
sun.security.validator.ValidatorException: 
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: 
unable to find valid certification path to requested target

该错误本质是 JDK 无法通过内置信任库（cacerts）构建到 repo.maven.apache.org 的可信证书链，而非 Maven 本身配置错误。

✅ 推荐解决方案（按优先级排序）

1️⃣ 【推荐】临时绕过验证（仅开发/调试用）

适用于快速验证是否为 SSL 问题本身，切勿用于 CI/CD 或生产环境：

mvn compile -Daether.connector.https.securityMode=insecure

此参数强制 aether（Maven 依赖解析引擎）跳过 HTTPS 证书校验。你也可将其设为全局环境变量以避免每次输入：

# Linux/macOS
export MAVEN_OPTS="-Daether.connector.https.securityMode=insecure"

# Windows（CMD）
set MAVEN_OPTS=-Daether.connector.https.securityMode=insecure

# Windows（PowerShell）
$env:MAVEN_OPTS="-Daether.connector.https.securityMode=insecure"

⚠️ 注意：insecure 模式会禁用整个 HTTPS 证书链验证（包括域名匹配、有效期、签名有效性等），存在中间人攻击风险，请严格限制使用场景。

2️⃣ 【最佳实践】更新 JDK 信任库（长期可靠）

根本性解决方式是确保 JDK 的 cacerts 信任库包含权威 CA 根证书（如 DigiCert、Sectigo 等），特别是当你的网络环境使用了企业代理或 SSL 解密网关时：

• 下载最新根证书包（如 Mozilla CA Certificate Store 的 cacert.pem）；
• 使用 keytool 导入关键根证书（示例导入 Let's Encrypt R3）：

# 下载 https://letsencrypt.org/certs/lets-encrypt-r3.pem
keytool -importcert -alias letsencrypt-r3 -file lets-encrypt-r3.pem \
  -keystore "$JAVA_HOME/jre
/lib/security/cacerts" -storepass changeit

? 提示：确认 $JAVA_HOME 指向 Maven 实际使用的 JDK（可通过 mvn -version 查看），并注意 cacerts 路径在 JDK 17+ 中可能为 $JAVA_HOME/lib/security/cacerts。

3️⃣ 【可选】降级传输实现（兼容旧行为）

若需恢复 Maven 3.8.x 的 httpclient 行为（例如已适配其代理/认证逻辑），可在 ~/.m2/settings.xml 中显式指定：

  
    httpclient
  

随后仍需确保 httpclient 相关依赖（如 org.apache.httpcomponents:httpclient）版本兼容，且代理配置正确。

? 总结与建议

• PKIX path building failed 是典型的 TLS 信任链断裂现象，根源在于 JDK 信任库缺失必要根证书；
• -Daether.connector.https.securityMode=insecure 是最快速的诊断手段，但仅为临时方案；
• 生产环境应优先通过更新 cacerts 或配置企业 CA 证书来修复信任链；
• 避免修改 Maven 安装目录下的 conf/settings.xml 全局配置，推荐使用用户级 ~/.m2/settings.xml 进行个性化设置；
• 若使用 IDE（如 IntelliJ IDEA），还需检查其内嵌 Maven 是否指向同一 JDK，并同步更新其信任库。

通过以上任一方式，即可稳定解决 Maven 3.9+ 构建中因 HTTPS 传输升级引发的证书验证失败问题。