Maven 报 release version 21 not supported：核对实际 JDK

源码构建先被 RequireMavenVersion 拦住，升级 Maven 后又报 release version 21 not supported，通常需要分开核对 Maven 的版本要求和实际编译器的能力。README 写着 JDK 17，不代表当前检出的 POM 仍以 Java 17 为目标。

例如 Neo4j 2026.06 的指定源码版本中，POM 要求 Maven 3.9.11，并把 maven.compiler.release 指向值为 21 的 vm.target.version。用 Maven 3.8.x 会先触发版本检查；改用合适 Maven、仍由 JDK 17 编译时，则无法接受 release 21。这些数字只适用于相应源码配置，不是所有 Neo4j 分支的统一安装要求。

先判断失败的是哪一道检查

保留首次失败目标和完整报错。下面是版本检查与编译错误的示例片段，环境数值应以自己的日志为准：

Detected Maven Version: 3.8.8 is not in the allowed range [3.9.11,).
error: release version 21 not supported

前一条表示运行构建的 Maven 不符合项目限定。它发生在编译之前，换 JDK 不会让 Maven 3.8.8 自动变成 3.9.11。后一条表示实际编译器不支持所选 release，下载更多业务依赖或清空本地仓库通常无法解决这个能力不匹配。

查看当前检出的父 POM、模块 POM、激活的 profile 和构建脚本。release 可能来自属性引用或环境变量覆盖；不要只查 README 或只搜索子模块中的一个数字。若分支、提交或 profile 已变化，重新取得这一版本的要求。

从真正执行构建的环境查看版本

在报错的终端、CI 步骤或构建容器中查看：

mvn -v
java -version
javac -version

mvn -v 给出 Maven 版本及运行 Maven 的 Java 环境。java、javac 的路径查找可能指向另一套安装，因此三条输出需要对照，不能只凭另一个终端的 java -version 判断失败构建用了什么。

没有配置其他编译器选择时，Maven 构建通常使用其运行 JDK 的编译能力。项目使用 Maven Toolchains 时，支持 toolchain 的编译插件可以使用独立于 Maven 运行环境的 JDK；还应核对项目选择的 toolchain、机器上的 toolchains.xml 及对应 jdkHome。配置了 fork 或明确编译器 executable 时，也检查实际选中的工具。

因此，看到 mvn -v 中是新 JDK，并不能在所有项目中证明编译器也已更新。相反，项目明确为编译选择了合适 toolchain 时，Maven 运行 JDK 和编译 JDK 不同也不必然是错误。

让构建工具满足项目要求

按当前源码要求选择受支持的 Maven 和 JDK，优先修改这一个项目的终端、IDE 构建配置或 CI 镜像。更改 JAVA_HOME 后，打开新的构建进程并再次检查 mvn -v；保留原环境配置，避免无意改变其他项目。

JAVA_HOME 指向 JDK 安装位置，实际路径依操作系统和安装方式决定。不要把某台 Linux 的 /usr/lib/jvm 路径复制到 macOS，也不要假定安装了 JDK 21 就会自动替换 CI 镜像里的 JDK 17。

Toolchains 项目应修改被项目实际选中的 JDK 配置，确认插件确实使用它。使用容器构建时，调整构建镜像或阶段；宿主机升级 Java 不会替换镜像内部的编译器。运行已部署数据库服务不属于这次源码构建修复，无需为检查编译环境而重启数据库。

--release 指定目标语言规则、字节码及相应 Java API，不是让旧 javac 获得未来版本能力。支持的目标通常包括当前 JDK 及有限的旧版本；不要简单认为任意更新 JDK 都适合所有旧项目，应遵守项目支持范围。

也不要删除 Maven Enforcer、降低 maven.compiler.release 或跳过检查来让第一条错误消失。项目代码和依赖可能确实需要该版本；改变目标需要单独评估兼容性，不能作为工具版本不匹配的默认修复。

从原失败步骤继续验收

先用调整后的环境重新执行原来失败的校验或模块编译，确认版本检查通过、编译器不再拒绝目标 release。随后执行项目要求的完整构建与测试。一个模块编译成功，只证明那一步已恢复，不能证明整个仓库、打包过程或运行时都已兼容。

构建会下载插件与依赖，并写入构建输出，应按项目正常的开发或 CI 环境验证。保存工具版本、选中的 JDK 路径及构建配置；需要回退时恢复原项目配置或镜像。如果旧配置本来无法构建当前分支，应使用此前确认兼容的源码与工具组合，而不是把回退本身当成问题已经解决。