Maven 与 JDK 版本排障

Java 项目最常见的环境错觉是：“命令行显示一个 Java 版本，但 Maven 实际使用另一个 JDK”。排障要按证据链逐层确认。

教程目标

定位并修复 invalid target release、release version not supported、字节码版本过高和本地/CI JDK 不一致。

第 1 步：收集证据

请只读排查当前项目的 Maven 与 JDK 环境，不要修改文件。

运行并解释：
- java -version
- javac -version
- mvn -version 或项目 Maven Wrapper
- JAVA_HOME（只显示路径，不显示其他环境变量）
- pom.xml 中 maven.compiler.release/source/target
- maven-compiler-plugin、toolchains 和 CI 的 JDK 配置

最后画出“当前实际 JDK → Maven JDK → 编译目标 → CI JDK”的对应关系。

优先使用项目的 mvnw / mvnw.cmd，它固定 Maven 版本，但不会自动固定 JDK。

第 2 步：按报错判断

报错	常见原因	先检查
invalid target release: 21	Maven 使用的 JDK 低于 21	mvn -version
release version 8 not supported	当前编译器或插件组合不支持该 release	JDK 与 compiler plugin
Unsupported class file major version	运行时低于依赖或产物的编译版本	运行 JDK 与依赖
本地通过、CI 失败	CI setup-java 与项目目标不一致	workflow 与构建日志
IDE 通过、命令行失败	IDE Project SDK 与 JAVA_HOME 不同	两套 JDK 路径

第 3 步：选择修复方向

项目要求 JDK 21 时，统一开发机、Maven、IDE 和 CI 到 21；项目必须兼容 JDK 17 时，把源码和依赖约束在 17 可用范围。不要仅为了通过构建降低 release，否则可能掩盖源码或依赖不兼容。

需要多 JDK 构建时使用 Maven Toolchains，并把 toolchains 文件当作本机配置，不提交包含私人绝对路径的版本。

第 4 步：让 Codex 做最小修改

根据已确认的项目目标 JDK，提出最小修复。
只允许修改必要的 pom.xml、Maven Wrapper 或 CI 配置。
不要同时升级 Spring Boot 和业务依赖。
修改前说明兼容影响和回滚方式，修改后展示 diff。

第 5 步：清洁验证

先运行版本命令，再运行项目真实的 clean test/package。多模块项目还要检查父 POM、模块覆盖配置和实际生成字节码目标。最后在 CI 使用相同 JDK 复验。

常见失败分支

• 修改 JAVA_HOME 后无效：重开终端并检查 PATH 中旧 Java。
• mvn 与 Wrapper 结果不同：项目统一使用 Wrapper。
• Maven 下载失败被误判为 JDK：先区分网络、仓库认证和 TLS 错误。
• IDE 仍报错：同步 Project SDK、Language Level 和 Maven Runner JDK。
• 多模块版本漂移：把共同编译配置放到父 POM，并检查子模块覆盖。

验收结果

1. java、javac、Maven、IDE 和 CI 的实际 JDK 可追溯。
2. 编译目标与项目支持策略一致，不靠盲目降低 release 绕过。
3. 只修改了必要环境或构建配置。
4. clean test/package 在目标 JDK 下通过。
5. CI 使用同一目标 JDK 并完成复验。

下一篇看：npm install 失败怎么拆开排查。