从 Java 17 迁移到 21/25

JDK 迁移不是把 JAVA_HOME 改成新路径。你需要分别验证运行时兼容、源码兼容、依赖与构建工具支持、性能行为和回滚能力。本文给出适用于 Java 17 → 21 → 25 的迁移清单。

Open Table of contents

先选择目标，不要一次改完所有东西

Java 21 和 25 都适合作为长期维护基线。目标版本还要结合云平台、应用服务器、APM Agent、JDBC 驱动和组织支持政策。不要在同一个发布中同时升级 JDK、框架大版本、数据库驱动和业务功能，否则失败时很难隔离变量。

先建立基线：

java --version
mvn --version
mvn test
mvn dependency:tree

记录启动时间、堆使用量、GC 暂停、吞吐量、错误率和关键接口延迟分位数。没有升级前数据，就无法证明升级后是否退化。

先运行，不重编译：让 Java 17 构建产物在目标 JDK 上运行全部测试和预生产流量。
升级工具和依赖：确认 Maven/Gradle、测试框架、Agent、驱动和字节码工具支持目标 JDK。
扫描内部 API：运行 jdeps --jdk-internals your-app.jar，替换 sun.* 等内部实现。
使用目标 JDK 编译：Maven 设置 <maven.compiler.release>21</maven.compiler.release>，不要只设置 source/target。
比较行为与性能：执行回归、压力、序列化、字符集、时区和 TLS 测试。
灰度并保留回滚：同一产物和配置支持切回旧运行时，逐步扩大实例比例。

Oracle 的 JDK 25 迁移指南也建议先在新 JDK 运行程序，再并行更新第三方库、重新编译并使用 jdeps 检查。

因此“应用启动成功”只验证了很小一部分。JDK 18 起默认字符集统一为 UTF-8，区域设置、时区数据和安全算法也可能随版本更新；涉及报表、签名和外部协议时必须做黄金样本对比。

Java 25 在 2025 年 9 月发布。不要把 Preview 特性直接作为长期公共 API；Preview 需要显式启用，后续版本仍可能变化。查看 JDK 25 语言变更汇总区分正式和预览特性，并查阅发行版供应商的许可与支持周期。

若 Gradle 构建迁移到 Java 25，Gradle 官方兼容矩阵显示运行 Gradle 需要 9.1.0 或更高版本；Maven、插件和 IDE 也要按各自兼容矩阵验证，不能只看业务源码。

迁移前在预生产真实执行一次回滚：停止新实例、用旧 JDK 启动同版本产物、恢复流量并验证监控。若新版本写出了旧版本无法读取的数据或缓存格式，单纯切换 JDK 不能回滚，必须提前设计双读或兼容窗口。

继续进入JVM 原理与性能诊断阶段，先理解类加载和字节码，再讨论垃圾回收与性能调优。