JetBrains IDE 怎样让 Gradle Toolchain 自动下载缺失 JDK

可以做到，但要先分清两件事：JetBrains IDE 的 Download JDK 负责把 JDK 安装并登记到项目里，Gradle Toolchain 的自动供应则由 Gradle 根据工具链声明和下载解析器寻找并管理缺失版本。只在 IDE 里选好 Gradle JVM，并不会自动给 java.toolchain 提供下载仓库。

官方地址：https://www.jetbrains.com/help/idea/gradle.html

步骤一：先把 IDE 的项目 JDK 与 Gradle JVM 分开看

打开 File > Project Structure > Project，确认 Project SDK。如果列表没有目标版本，从 SDK 下拉框选择 Download JDK，再选择版本、发行商和安装位置。随后打开 Settings > Build, Execution, Deployment > Build Tools > Gradle，查看 Gradle JVM。

这里的可见成功状态是两个字段都指向可用 JDK，且 Gradle 项目不再显示 unresolved JDK。IDE 自带的 JetBrains Runtime 是运行 IDE 的 Java，不等于项目要用的编译工具链。

步骤二：让 Gradle 有可用的 JDK 下载解析器

在项目根目录打开 settings.gradle.kts，加入一个 Toolchain Resolver。下面使用 Gradle 文档示例中的 Foojay convention 插件；版本号应按团队的依赖策略固定，不要让每台开发机随意漂移：

plugins {
    // 为缺少的 Java Toolchain 提供可查询的下载解析器
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

rootProject.name = "toolchain-demo"

点击 IDE 顶部的 Sync Project with Gradle Files，如果同步能解析该插件，说明下载仓库入口已经接上。企业网络若拦截外部仓库，应先配置允许的代理或内部镜像，否则后面会把“解析失败”误判成 JDK 版本问题。

步骤三：声明 Java Toolchain 并触发同步

在 build.gradle.kts 的 java 扩展中声明目标版本。这个声明控制编译、测试和 Javadoc 等任务使用的 Java 版本，不是把 IDE 的启动 JDK 改成同一个版本：

plugins {
    // 使用 Java 插件提供 java.toolchain 配置
    java
}

java {
    // 构建需要 Java 17；本机没有匹配版本时交给 resolver 处理
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

保存文件后点击 Gradle 工具窗口的 Reload All Gradle Projects。若本机没有 Java 17，Gradle 会在已配置下载解析器且网络可用时自动获取匹配的 GA JDK；预览版并不属于这条自动供应路径。图中的 Downloaded 与 Ready 只是帮助定位状态的静态说明。

步骤四：用工具链列表和设置面板验收

在 Gradle 工具窗口运行 javaToolchains 任务，或在项目目录执行：

# 列出 Gradle 检测到的 JDK、版本、供应商和自动下载状态
./gradlew -q javaToolchains

重点看三项：目标版本是否出现、Auto-detection 是否开启、Auto-download 是否开启。若只看到 Project SDK 而没有目标 Toolchain，依次检查 settings.gradle.kts 的 resolver 插件、Gradle Wrapper 版本、网络代理和 JDK 版本是否是 GA 发行版。

常见问题

只在 IDE 里点击 Download JDK，Gradle 就会自动满足所有 Toolchain 吗？

不一定。它会把指定 JDK 安装并登记到 IDE，Gradle 是否能满足另一个版本仍取决于工具链声明、自动检测和下载解析器。

为什么项目能同步，但构建仍提示找不到 JDK？

同步使用的 Gradle JVM 与任务需要的 Toolchain 可能不同。先运行 javaToolchains，再检查目标版本和 resolver，而不是只反复切换 Gradle JVM。

能否用 JAVA_HOME 代替 Toolchain 配置？

JAVA_HOME 适合指定当前进程默认 Java，不能表达项目要在多版本之间选择的 Toolchain 约束。需要可复现构建时，应保留 java.toolchain 声明。

最终判断标准是：IDE 能打开并同步项目，Gradle 能列出目标 Toolchain，缺少本地 JDK 时 resolver 能提供可用的 GA 版本。把这三层分别配置，才是 JetBrains IDE 配合 Gradle 自动获取缺失 JDK 的稳定做法。