Gradle指定本地JDK工具链需四步：一在gradle.properties中用org.gradle.java.installations.paths显式注册路径；二在build.gradle中用JavaLanguageVersion.of(21)声明语言版本；三确保子项目及Android项目android块内分别配置；四同步IDEA时清理缓存并重新导入。

Gradle Java项目指定本机已有的工具链，核心是让 java.toolchain 明确指向你本地已安装、但未被自动识别的 JDK（比如 JDK 21 安装在 /opt/jdks/jdk-21.0.3，却没出现在 org.gradle.java.installations.paths 自动扫描路径里）。

怎么让 Gradle 找到你手动装的 JDK

Gradle 工具链默认只扫描标准路径（如 $HOME/.sdkman/candidates/java、/usr/lib/jvm 等），如果你把 JDK 解压到自定义目录，它不会自动发现。必须显式告诉 Gradle：“就用这个路径”。

• 在 gradle.properties 中添加：

  org.gradle.java.installations.paths=/opt/jdks/jdk-21.0.3,/opt/jdks/jdk-17.0.2

  （多个路径用英文逗号分隔，路径末尾不加斜杠）
• 确保该路径下存在 bin/java 和 lib/jmods（否则 Gradle 会跳过该安装）
• 不要同时设置 org.gradle.java.installations.auto-detect=false —— 关闭自动探测后，Gradle 就只认你写的路径，但不会报错提示“找不到”，而是静默 fallback 到运行 Gradle 的 JDK，极易误判

build.gradle 里怎么选中它

光注册路径还不够，得在构建脚本里声明使用哪个版本。工具链匹配靠的是 languageVersion，不是路径名或文件夹名。

Java 接口排错助手

在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。

下载

• 写法必须是 JavaLanguageVersion.of(21)，不能写成 "21"、21（数字字面量）或 JavaLanguageVersion.VERSION_21（已废弃）
• 要覆盖所有 Java 编译任务：

  java {
      toolchain {
          languageVersion = JavaLanguageVersion.of(21)
      }
  }
  tasks.withType(JavaCompile).configureEach {
      javaCompiler.set(javaToolchains.compilerFor(JavaLanguageVersion.of(21)))
  }

• 如果项目含测试代码，还要单独配测试编译器：

  test {
      javaLauncher = javaToolchains.launcherFor(JavaLanguageVersion.of(21))
  }

为什么明明配置了还用错 JDK

常见现象：./gradlew compileJava 输出显示用了 JDK 17，但 java -version 是 21，gradle.properties 也写了路径——问题往往出在层级覆盖。

立即学习“Java免费学习笔记（深入）”；

• settings.gradle 或根 build.gradle 里配的 toolchain 只影响当前项目，子项目（如有）需各自声明
• Android 项目里 AGP（Android Gradle Plugin）可能重置 toolchain，必须在 android {} 块内再写一遍：

  android {
      compileSdk = 34
      compileOptions {
          sourceCompatibility = JavaVersion.VERSION_21
          targetCompatibility = JavaVersion.VERSION_21
      }
      kotlinOptions {
          jvmTarget = "21"
      }
  }

  （注意：这里仍是旧式配置，和 toolchain 并存时以 toolchain 为准，但 AGP 某些版本会忽略 toolchain，所以双保险更稳）
• IDEA 同步后仍显示老 JDK：删掉 .idea/misc.xml 里的 <component name="ProjectRootManager"></component> 段，重启并重新 Import Gradle project

工具链不是“设一次就完事”的开关，它是按任务粒度生效的；本地 JDK 路径注册、语言版本声明、作用域覆盖、IDE 同步这四步缺一不可。最容易漏的是子项目独立声明和 AGP 下的二次适配。