结论是：Maven Toolchains 的核心作用是让 maven-compiler-plugin、maven-javadoc-plugin 等插件绕过 JAVA_HOME，改用 toolchains.xml 中明确定义的 OpenJDK 路径执行工具命令；它不改变 Maven 运行时 JDK，仅接管编译、签名、文档生成等具体工具调用，且每个插件必须显式配置 true 才生效。
直接说结论：用 Maven Toolchains 管理 OpenJDK，核心不是“选哪个 JDK”，而是“让 maven-compiler-plugin、maven-javadoc-plugin 等插件绕过当前 JAVA_HOME，改用你明确声明的 OpenJDK 路径执行命令”。它不改变 Maven 运行时的 JDK，只接管编译、签名、生成文档等具体工具调用。
toolchains.xml 里怎么写 OpenJDK 的路径
OpenJDK 和 Oracle JDK 在 Toolchains 中没有本质区别，关键看 <jdkhome></jdkhome> 是否指向真实安装目录，且该目录下有 bin/javac。常见错误是路径末尾多写了 /jre 或漏了 /Contents/Home（macOS）。
- Linux / macOS 上，OpenJDK 通常解压即用，路径类似
/opt/jdk-17.0.2或/usr/lib/jvm/java-17-openjdk-amd64；确认后填入<jdkhome></jdkhome> - Windows 上注意反斜杠转义或用正斜杠，例如
C:/Program Files/Java/jdk-17.0.2 -
<version></version>填17、17.0或17.0.2都可以，Maven 只做字符串匹配，不校验语义；但建议统一用17避免和maven-compiler-plugin的source/target混淆 - 不要写
<vendor>openjdk</vendor>—— Toolchains 不校验 vendor，留空或写oracle都不影响，但写错可能让某些旧版插件跳过匹配
maven-compiler-plugin 必须启用 toolchain 支持
即使配置了 toolchains.xml，如果插件没主动请求 toolchain，它仍会用当前 JVM 的 javax.tools.JavaCompiler 或 JAVA_HOME 下的 javac。从 maven-compiler-plugin 3.6.0+ 开始，需显式开启：
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
<configuration>
<useToolchain>true</useToolchain>
</configuration>
</plugin>
- 这个
<usetoolchain>true</usetoolchain>是开关，缺了就等于没配 toolchain - 不需要再配
<executable></executable>或fork=true，toolchain 机制会自动替换javac调用路径 - 如果项目同时用了
maven-javadoc-plugin或maven-jarsigner-plugin，它们也得各自加<usetoolchain>true</usetoolchain>才生效
为什么 mvn compile 成功但 mvn javadoc 失败
这是最典型的 toolchain 漏配场景：maven-compiler-plugin 启用了 toolchain，但 maven-javadoc-plugin 没启，导致编译用 OpenJDK 17，而 javadoc 还在用系统默认 JDK 8 的 javadoc 工具，直接报 java.lang.UnsupportedClassVersionError。
- 检查所有用到 JDK 工具的插件是否都加了
<usetoolchain>true</usetoolchain>，重点包括：maven-compiler-plugin、maven-javadoc-plugin、maven-jarsigner-plugin、maven-surefire-plugin（测试运行时若依赖特定 JDK） - 运行
mvn -X compile看 debug 日志，搜索toolchain关键字，确认是否找到匹配的jdktoolchain - 运行
mvn help:effective-pom，确认插件配置确实被合并进最终 pom，避免被父 POM 覆盖
真正容易被忽略的是：toolchain 匹配成功 ≠ 插件实际使用它。每个插件必须独立声明启用，而且必须用支持 toolchain 的版本（如 maven-compiler-plugin 3.6.0+）。别假设“配了 toolchains.xml 就万事大吉”——它只是资源池，谁去取、怎么取，全看插件自己有没有伸手。
