Maven toolchains 怎样固定构建 JDK

项目里同时装着 JDK 17 和 JDK 21 时，最容易踩到的坑不是“没有 JDK”，而是 Maven 启动时选中的 JDK 和编译、测试真正需要的 JDK 不是同一个。Maven toolchains 的做法是把选择条件放进项目，把安装目录放进构建机的 toolchains.xml，让支持 toolchain 的插件从同一份匹配结果取 JDK。

官方地址：https://maven.apache.org/guides/mini/guide-using-toolchains.html

先把 Maven 运行环境和构建 JDK 分开

toolchains 解决的是“哪个 JDK 执行编译、测试或其他工具链感知目标”，不是“哪个 JDK 启动 Maven”。例如 CI 镜像用 JDK 21 启动 Maven，但项目仍要求用 JDK 17 编译；这时不必把每个插件都写成固定的 /opt/jdk-17/bin。

下面的示例以 JDK 17 为主版本。项目文件只声明需求，具体目录留在构建机侧，这样开发机、CI 和发布机可以使用各自的安装路径。

用 toolchains.xml 注册可用的 JDK

在构建机的 ${user.home}/.m2/toolchains.xml 写入 JDK 条目。jdkHome 必须指向 JDK 根目录，而不是 bin 子目录；同一个文件可以登记多套 JDK。

jdk17temurin/opt/jdks/temurin-17

这个文件描述“机器上有哪些候选”，不代表项目一定会选中它。项目的条件还要在 POM 里声明；如果 vendor 或版本对不上，插件找不到满足全部条件的工具链。

在 pom.xml 里提出项目的 JDK 条件

在项目中加入 maven-toolchains-plugin，让它把匹配到的 JDK 放入 Maven 会话，随后由支持 toolchain 的编译、测试等插件使用。下面的配置把版本和发行商都写成明确条件。

org.apache.maven.pluginsmaven-toolchains-plugin3.3.0toolchain17temurin

如果自动发现工具链写入的是完整版本，例如 17.0.20，单写 17 不一定匹配。希望接受 JDK 17 的补丁版本时，可改为 [17,18)；Java 8 则要根据条目写法选择 [8,9) 或 [1.8,1.9)。范围比强行改路径更适合多台构建机。

用清单确认它真的适合当前构建

官方指南列出了多个 toolchain-aware 插件。若某个插件不读取 MavenSession 中的工具链，toolchains 配好了也不会改变它的执行 JDK。对单个编译器、测试或 Javadoc 任务有特殊需求时，可以查看该插件自己的 jdkToolchain 参数；它可能覆盖全局选择。

常见问题

Maven toolchains 会修改 JAVA_HOME 吗？

不会。它只向 Maven 会话提供构建工具链，启动 Maven 的 Java 进程仍由当前环境决定。

为什么写了 17 还是找不到 JDK？

优先检查 toolchains.xml 是否被放在当前用户的 .m2 目录、jdkHome 是否为真实 JDK 根目录，再检查版本值和 vendor 是否同时匹配。

CI 上应该把 toolchains.xml 提交到仓库吗？

通常不提交含绝对路径的机器配置。可以在 CI 初始化阶段生成或注入该文件，项目 POM 保留稳定的版本条件，避免把某台机器的目录写死。

只想让 compiler 使用另一套 JDK 怎么办？

查看 maven-compiler-plugin 的 jdkToolchain 配置。它适合单插件覆盖场景，但要同步确认测试、打包和 Javadoc 是否仍使用另一套 JDK。

固定构建 JDK 的关键不是让每台机器拥有相同路径，而是把“项目需要什么”与“本机在哪里”拆开：POM 写匹配条件，toolchains.xml 写安装目录，最后只把支持 toolchain 的插件纳入验收清单。