Java 项目中常见的环境偏差是“系统命令行版本与 Maven 实际使用的 JDK 不一致”。排障需按证据链逐层确认，避免盲目修改配置。

核心排查思路

当遇到 invalid target release 或 Unsupported class file major version 时，应首先确认整个链路的 JDK 版本对应关系：

系统 JAVA_HOME -> Maven 运行 JDK -> 项目编译目标版本 -> CI/CD 构建环境。

常见错误类型与原因

| 报错现象 | 核心原因 | 优先检查项 |

| :--- | :--- | :--- |

| invalid target release: XX | Maven 使用的运行 JDK 低于目标版本 | mvn -version |

| release version X not supported | 编译器或插件组合不支持该版本 | JDK 与 compiler plugin 匹配度 |

| Unsupported class file major version | 运行时 JDK 低于依赖或产物的编译版本 | 运行时 JDK 版本 |

| 本地通过但 CI 失败 | CI 的 setup-java 与项目目标不一致 | CI workflow 定义 |

| IDE 通过但命令行失败 | IDE 设置的 Project SDK 与系统环境变量不同 | 环境变量 JAVA_HOME |

排查步骤建议

第一步：环境快照

要求 Codex 运行并解释以下输出：

  • java -version 与 javac -version
  • mvn -version
  • 系统 JAVA_HOME 路径
  • pom.xml 中的 maven.compiler.release/source/target 配置

第二步：优先使用 Wrapper

在多环境协作中，优先使用项目根目录的 mvnw (Maven Wrapper)，以固定 Maven 版本，减少环境差异。

第三步：多模块版本一致性

对于多模块项目，检查父 POM 的共同配置，防止子模块出现版本漂移或意外覆盖。

修正原则

  • 最小化改动：仅修改必要的 pom.xml、Wrapper 或 CI 配置，不要同时升级不相关的业务依赖。
  • 不盲目降级：不要为了通过构建而盲目降低 release 版本，这可能会掩盖真实的兼容性问题。
  • 保持环境闭环：修改后务必运行 clean test/package，并在 CI 环境中完成复验。

做到环境可追溯、配置可预测，是解决 Java 构建问题的关键。