Java Toolchain是Gradle统一调度编译、测试、打包所用JDK的机制，比sourceCompatibility更可靠，因它主动查找并锁定匹配JDK，而非被动依赖JAVA_HOME或系统默认JDK。
Gradle 7.0+ 默认启用 Java Toolchain，它能自动匹配项目所需 JDK 版本，不再依赖本地 JAVA_HOME —— 这意味着你用 JDK 21 写代码，但项目要求编译成 Java 17 字节码，Toolchain 会自动找系统里已安装的 JDK 17 来执行 javac，哪怕 JAVA_HOME 指向的是 21。
Java Toolchain 是什么，为什么比 sourceCompatibility 更可靠
Toolchain 是 Gradle 对“用哪个 JDK 编译、用哪个 JDK 运行测试、用哪个 JDK 打包”的统一调度机制。它不只控制语法（sourceCompatibility）和字节码版本（targetCompatibility），还真正约束了构建工具链本身所用的 JDK 实例。
常见错误现象：
- 你在 build.gradle 里写了
sourceCompatibility = JavaVersion.VERSION_17，但本地只有 JDK 21，CI 上却报Unsupported class file major version 65 - 多模块项目中，一个模块设了 Java 17，另一个设了 Java 8，结果 Gradle 用同一个 JDK 编译全部，导致字节码混杂
Toolchain 解决的就是这类“编译器版本失控”问题：它让 Gradle 主动去查、去选、去下载（可选）、去锁定 JDK，而不是被动依赖环境变量。
立即学习“Java免费学习笔记（深入）”；
在 build.gradle 中声明 Java Toolchain 的标准写法
只需在 java 插件配置块内加一段 toolchain 块即可，无需额外插件或 Groovy 辅助逻辑。
示例（Groovy DSL）：
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
说明与要点：
-
languageVersion是必须项，它同时决定sourceCompatibility和targetCompatibility的隐式值（除非你显式覆盖） - Gradle 会按以下顺序查找匹配的 JDK：
JAVA_HOME→PATH中的javac→ 系统注册表（Windows）//usr/libexec/java_home（macOS）//usr/lib/jvm（Linux） - 如果没找到，Gradle 默认不报错，而是 fallback 到当前运行 Gradle 的 JDK —— 这是容易被忽略的风险点
- 若要强制失败（推荐 CI 场景），加上
vendor = JvmVendorSpec.ADOPTIUM或implementation = JvmImplementation.VENDOR_SPECIFIC可缩小搜索范围，提高确定性
如何验证 Toolchain 是否生效，以及常见失效原因
最直接的方式是运行 ./gradlew javaToolchains（Gradle 7.3+），它会列出所有已识别的 JDK 及其匹配状态。
常见失效原因：
- 本地没装对应版本 JDK：比如
languageVersion = 17，但系统里只有 JDK 8 和 JDK 21 —— Gradle 不会自动下载，也不会报错，只是静默 fallback - macOS 上未安装
adoptium或temurin，而只用了 Oracle JDK，可能因签名或路径格式不被识别 - Windows 上 JDK 安装路径含空格且未被正确解析（如
C:\Program Files\Java\jdk-17.0.2），建议统一用无空格路径，例如C:\Java\jdk-17.0.2 - 在
settings.gradle中启用了enableFeaturePreview('VERSION_CATALOGS')，但未同步升级 Gradle Wrapper 版本（需 ≥ 7.4）
验证命令输出中看到 matched: true 且 metadata.version 显示 17.0.x，才算真正命中。
多模块项目中各模块使用不同 Java 版本的实操方式
Toolchain 支持 per-project 配置，即每个子模块可独立指定 languageVersion，Gradle 会为每个模块分别解析和绑定 JDK。
例如，在 service/build.gradle 中：
java {
toolchain {
languageVersion = JavaLanguageVersion.of(11)
}
}
而在 api/build.gradle 中：
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
注意点：
- 父项目
build.gradle中的java { toolchain { ... } }不会继承给子模块，必须显式声明 - 如果某模块未声明，它将 fallback 到当前运行 Gradle 的 JDK，不是继承父项目的设置
- 跨模块依赖时，Gradle 不检查 ABI 兼容性（比如 Java 17 模块引用 Java 11 模块），这仍需靠人肉确认或
dependencyInsight辅助分析
真正麻烦的从来不是配置本身，而是当某个模块悄悄升级了语言版本（比如加了 sealed 类），而依赖它的模块还在 Java 11 下编译 —— 这种不兼容不会在 build 阶段暴露，只会在运行时报 java.lang.IncompatibleClassChangeError。
