“PKIX path building failed”错误源于JDK cacerts缺少对应CA根证书，需用keytool将企业CA证书导入$JAVA_HOME/lib/security/cacerts并重启相关进程，同时排查Maven/Gradle是否覆盖了默认trustStore配置。
依赖下载失败时提示“PKIX path building failed”
这是最常见的证书问题表现，Maven 或 Gradle 在拉取远程仓库（如 Maven Central、JFrog）时，JVM 无法验证服务器 TLS 证书链。根本原因不是证书“不合法”，而是 JDK 自带的 truststore（$JAVA_HOME/lib/security/cacerts）里缺少对应 CA 根证书，尤其在企业内网或使用自签名代理时高频出现。
- 先确认错误是否真由证书引起：运行
mvn -X clean compile，搜索日志中是否含sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target - 不要直接禁用 SSL 验证（如加
-Dmaven.wagon.http.ssl.insecure=true），这会绕过全部证书校验，破坏构建安全性 - 区分环境：开发机可能已手动导入过证书，但 CI 服务器（如 Jenkins agent）用的是干净 JDK，
cacerts未同步更新
把企业 CA 证书导入 JDK 的 cacerts
必须向运行构建工具的 JVM 的 cacerts 添加信任，而不是只改浏览器或系统证书库。不同 JDK 版本路径一致，但需注意权限和生效范围。
- 找到目标 JDK 的
cacerts文件：$JAVA_HOME/lib/security/cacerts（JDK 8–17 均适用；JDK 17+ 若用java -version显示 “Temurin” 或 “Zulu”，路径不变） - 用
keytool导入（需管理员/root 权限）：keytool -importcert -alias my-company-ca -file /path/to/company-root-ca.crt -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
其中changeit是 JDK 默认密钥库密码，若被修改过需替换为实际密码 - 导入后重启所有依赖该 JDK 的进程（IDE、CI agent、终端 shell），否则 JVM 缓存旧 truststore
Gradle 和 Maven 各自的证书配置差异
即使 JDK 级证书已修复，构建工具仍可能因独立配置覆盖默认行为。重点检查是否显式指定了 javax.net.ssl.trustStore 或代理相关参数。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- Maven：检查
~/.m2/settings.xml是否有<mirrors></mirrors>指向 HTTPS 内网仓库但未配对应证书；检查MAVEN_OPTS是否含-Djavax.net.ssl.trustStore=...—— 若指向一个过期或空的 truststore，会完全屏蔽cacerts - Gradle：检查
gradle.properties是否设置了systemProp.javax.net.ssl.trustStore；更隐蔽的是init.gradle中调用System.setProperty("javax.net.ssl.trustStore", ...)，这类代码会强制覆盖 JVM 启动参数 - CI 场景下：Docker 构建镜像若基于
maven:3.9-openjdk-17等官方镜像，其cacerts是纯净的，必须在 Dockerfile 中显式RUN keytool -importcert ...
调试证书链是否真正生效
光看构建成功不够，得验证 JVM 实际使用的 truststore 和证书路径是否符合预期。最直接的方式是让 JVM 打印 SSL 握手细节。
立即学习“Java免费学习笔记（深入）”；
- 临时启用 JVM 调试输出：
export MAVEN_OPTS="-Djavax.net.debug=ssl:trustmanager"（Maven）或export GRADLE_OPTS="-Djavax.net.debug=ssl:trustmanager"（Gradle） - 执行构建后，搜索日志中
adding as trusted cert行，确认你的my-company-ca别名出现在加载列表里 - 若仍失败，检查证书格式：
keytool -list -v -keystore $JAVA_HOME/lib/security/cacerts | grep "my-company-ca"确认别名存在且未被重复导入（重复别名会导致覆盖）
