Java invalid target release — JDK 或编译参数不符

症状

本篇调试指南针对“Java invalid target release — JDK 或编译参数不符”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。

可观察到的症状包括：

• 编译失败并提示 “invalid target release: 17”
• 一台机器可构建，CI 失败
• Maven/Gradle 报告的目标版本与 java -version 不一致

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

mvn -version && javac -version && echo "$JAVA_HOME"

运行 JDK 必须不低于请求的发布版本；不匹配即产生 invalid target release。

步骤 2

grep -rn "release>\|source>\|target>\|compiler.release" pom.xml build.gradle

配置的 release 决定应安装哪个 JDK，或应下调哪个值。

常见诱因（按出现频率排序）：

• 编译器运行的 JDK 低于要求的目标版本
• maven.compiler.release 或 sourceCompatibility 超过已安装 JDK
• JAVA_HOME 指向的 JDK 与 PATH 上的不同

根因

javac 无法生成比执行编译的 JDK 更新的目标字节码。用 JDK 11 工具链请求 release 17，会在产出任何类之前报 invalid target release。

修复

安装并选用匹配的 JDK（设置 JAVA_HOME 与 PATH），让 maven.compiler.release/sourceCompatibility 与可用 JDK 对齐，或用 toolchains 独立固定编译 JDK。

注意：为匹配旧 JDK 而降低目标可能发布缺少特性与安全修复的字节码；更应安装正确的 JDK。

<!-- Maven toolchains: compile with JDK 17 regardless of runtime -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
  <configuration>
    <release>17</release>
  </configuration>
</plugin>

# verify the bytecode version
javap -v target/classes/com/example/Main.class | grep 'major version'

验证

重新构建并确认编译成功；用 javap -v 检查生成的类文件版本与目标一致。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。