java项目升级jdk需确保编译、运行、依赖、构建工具四者对齐，重点验证版本一致性、第三方库兼容性、强封装配置（--add-opens）、模块移除适配及ci/cd环境同步，并清理构建缓存。
Java 项目升级 JDK 版本不是改个配置就能完事的，核心问题在于：编译、运行、依赖、构建工具四者必须对齐新 JDK 的语义与能力边界。跳过验证环节直接切版本，大概率会在 CI 构建失败、运行时 NoClassDefFoundError、或 UnsupportedClassVersionError 上卡住。
确认当前 JDK 版本和项目实际使用版本
别只看 java -version，它只反映 shell 环境默认 JDK；很多 IDE 或构建工具会覆盖它。
- 在终端执行
javac -version和java -version，确认编译器与运行时是否一致 - IDEA 用户检查：
File → Project Structure → Project → Project SDK / Project language level - Maven 项目必须核对
pom.xml中的maven-compiler-plugin配置：<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <source>17</source> <target>17</target> <release>17</release> </configuration> </plugin>注意：<release></release>是关键——它启用跨 JDK 兼容编译（如用 JDK 21 编译出能在 JDK 17 上跑的字节码），但会禁用新版本 API，适合保守升级
检查第三方库是否支持目标 JDK
很多老库（尤其是 Spring Boot 2.x、Hibernate 5.x、Log4j 1.x）在 JDK 17+ 会因模块系统（JPMS）或废弃 API 报错，比如 java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext（JDK 11 移除了 JAXB）。
- 查 Maven 仓库页面，看库的
Compatibility或Release Notes是否声明支持目标 JDK - 用
jdeps --jdk-internals your-app.jar检查是否调用了已移除的内部 API（如sun.misc.Unsafe） - 常见兼容组合参考：
- Spring Boot 2.7.x → 最高支持 JDK 17（不支持 21）
- Spring Boot 3.0+ → 要求 JDK 17+，且默认启用 Jakarta EE 9+ 命名空间（
jakarta.*替代javax.*） - Lombok 1.18.28+ → 支持 JDK 21；旧版在 JDK 17+ 可能触发
IllegalAccessError
处理 JDK 17+ 引入的关键变更
JDK 17 是 LTS，但也是第一个强制启用强封装（Strong Encapsulation）的版本，影响远超语法更新。
立即学习“Java免费学习笔记（深入）”；
-
--add-opens参数必须显式加到 JVM 启动参数中，否则反射访问受限类会抛InaccessibleObjectException，例如：--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED
Maven Surefire 插件需同步配置：<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <jvm>--add-opens java.base/java.lang=ALL-UNNAMED</jvm> </configuration> </plugin> - JDK 21 的虚拟线程（
VirtualThread）默认不启用，需加--enable-preview，且不能用于生产环境（除非明确接受预览特性风险） - JDK 17 移除了
java.security.acl、java.xml.ws等模块，若代码直接 import 这些包，必须替换为标准替代方案（如用jakarta.xml.ws）
CI/CD 和容器环境同步更新
本地能跑 ≠ 测试环境能跑。Dockerfile、GitHub Actions、Jenkins agent 的 JDK 往往是硬编码的。
- Dockerfile 示例（以 Adoptium JDK 21 为例）：
FROM eclipse-temurin:21-jre-jammy COPY target/app.jar /app.jar ENTRYPOINT ["java", "-jar", "/app.jar"]
注意镜像 tag 必须匹配 JDK 主版本（21-jre-jammy≠17-jre-jammy） - GitHub Actions 中避免用
actions/setup-java@v3默认 latest，应锁定版本：- uses: actions/setup-java@v4 with: java-version: '21' distribution: 'temurin' - Kubernetes Pod 中的
java -version输出可能被initContainer或 sidecar 覆盖，建议在主容器启动脚本里加echo "JDK: $(java -version 2>&1)"日志输出
最常被忽略的是构建缓存：Maven 的 target/ 目录、Gradle 的 build/、IDE 的索引文件，都可能残留旧 JDK 生成的 class 文件或 metadata。升级前清掉它们，比反复调试 UnsupportedClassVersionError 更省时间。
