JVM 项目的工具链 - Gradle 构建系统

在多个项目上工作可能需要与多个版本的 Java 语言交互。即使在单个项目中，代码库的不同部分也可能由于向后兼容性要求而固定到特定的语言级别。这意味着必须在构建项目的每台机器上安装和管理相同工具（工具链）的不同版本。

Java 工具链是构建和运行 Java 项目的一组工具，通常由环境通过本地 JRE 或 JDK 安装提供。编译任务可以使用 javac 作为其编译器，测试和执行任务可以使用 java 命令，而 javadoc 将用于生成文档。

默认情况下，Gradle 对运行 Gradle 本身和构建 JVM 项目使用相同的 Java 工具链。但是，这并非总是可取的。在不同的开发机器和 CI 服务器上使用不同的 Java 版本构建项目可能会导致意外问题。此外，您可能希望使用不支持运行 Gradle 的 Java 版本来构建项目。

为了提高构建的可复现性并使构建要求更清晰，Gradle 允许在项目和任务级别配置工具链。您还可以使用守护进程 JVM 条件控制用于运行 Gradle 本身的 JVM。

项目工具链

Gradle 提供了多种方法来配置用于编译和运行项目的 Java 版本。

五种主要机制是

Java 工具链
--release 标志
源和目标兼容性
环境变量 (JAVA_HOME)
IDE 设置

这些设置并非相互排斥，高级用户可能需要在特定场景中组合它们。

1. Java 工具链

要为项目配置工具链，请在 java 扩展块中声明所需的 Java 语言版本

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

java 块是灵活的，支持额外的配置选项。您可以在使用 Java 工具链中了解更多信息。

2. `--release` 标志

对于严格的交叉编译，建议使用 --release 标志而不是 sourceCompatibility 和 targetCompatibility

tasks.withType<JavaCompile>().configureEach {
    options.release = 8
}

tasks.withType(JavaCompile).configureEach {
    options.release = 8
}

此标志可防止意外使用指定版本中不可用的较新 API。但是，它不控制使用哪个 JDK，只控制编译器如何处理源代码。

如果您既需要特定的 JDK 又需要严格的交叉编译，则此方法可以与工具链结合使用。

3. 源和目标兼容性

设置 sourceCompatibility 和 targetCompatibility 告诉 Java 编译器生成与特定 Java 版本兼容的字节码，但不强制 Gradle 本身运行的 JDK

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

这不保证使用正确的 JDK，并且当 API 已向后移植到较旧的 Java 版本时可能会导致问题。

您只应在需要向后兼容性但无法使用工具链的情况下使用此方法。

4. 环境变量 (`JAVA_HOME`)

您可以通过设置 JAVA_HOME 环境变量来影响 Gradle 使用的 JDK

export JAVA_HOME=/path/to/java17

这会为系统上的所有基于 Java 的工具（包括 Gradle 和 Maven）设置默认 JDK。

这不会覆盖 Gradle 的工具链支持或其他项目特定的配置。

此方法对于不使用工具链并期望环境中激活特定 JDK 的遗留项目很有用。

但是，由于 JAVA_HOME 全局适用，因此无法用于为不同的项目指定不同的 JDK 版本。使用工具链更可靠，它允许在项目级别设置 Java 版本。

5. IDE 设置

大多数现代 IDE 允许您在处理项目时配置用于运行 Gradle 的 JVM。此设置会影响 Gradle 本身在 IDE 中的执行方式，但不会影响代码的编译方式——除非构建未明确指定工具链。

如果您的构建未定义 Java 工具链，Gradle 可能会回退到使用 IDE 设置定义的 Java 版本。这可能导致意外且不可重现的行为，特别是当不同的团队成员使用不同的 IDE 配置时。

您应该更改 IDE 的 Gradle JVM 设置，使其与命令行上使用的 JVM（JAVA_HOME 或系统的默认 Java 安装）对齐——确保跨环境的一致行为（例如，从 IDE 运行测试或任务与从终端运行测试或任务）。

如果 IDE 在 JVM 未设置或与 JAVA_HOME 不匹配时发出警告/错误，您还应该更改 IDE 的 Gradle JVM 设置。

IntelliJ IDEA

配置 Gradle JVM

打开 Settings (Preferences) > Build, Execution, Deployment > Gradle。
将 Gradle JVM 设置为所需的 JDK。

Eclipse

配置 Gradle JVM

打开 Preferences > Gradle > Gradle JDK。
选择适当的 JDK。

一些 IDE 还允许您在相同的设置屏幕中配置Gradle Daemon JVM。注意不要将其与工具链或项目 JVM 混淆——确保您选择了正确的 JVM。

组合工具链

在某些情况下，您可能希望

使用特定 JDK 版本进行编译（toolchains）。
确保编译后的字节码与旧 Java 版本兼容（--release 或 targetCompatibility）。

例如，用 Java 17 编译但生成 Java 11 字节码

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

tasks.withType<JavaCompile>().configureEach {
    options.release = 11
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

tasks.withType(JavaCompile).configureEach {
    options.release = 11
}

项目工具链设置对比表

方法确保正确的 JDK？自动下载 JDK？防止意外 API 使用？

方法	确保正确的 JDK？	自动下载 JDK？	防止意外 API 使用？
Java 工具链	✅ 是	✅ 是	❌ 否
`--release` 标志	❌ 否	❌ 否	✅ 是
源和目标兼容性	❌ 否	❌ 否	❌ 否
环境变量 (`JAVA_HOME`)	✅ 是（但仅限于全局）	❌ 否	❌ 否
IDE 设置	✅ 是（在 IDE 内部）	❌ 否	❌ 否

Java 工具链

✅ 是

❌ 否

--release 标志

❌ 否

✅ 是

源和目标兼容性

❌ 否

环境变量 (JAVA_HOME)

✅ 是（但仅限于全局）

❌ 否

IDE 设置

✅ 是（在 IDE 内部）

❌ 否

任务工具链

如果您想微调特定任务使用的工具链，您可以指定任务使用的确切工具。例如，Test 任务公开了一个 JavaLauncher 属性，该属性定义用于启动测试的 Java 可执行文件。

在下面的示例中，我们将所有 Java 编译任务配置为使用 Java 8。此外，我们引入了一个新的 Test 任务，该任务将使用 JDK 17 运行我们的单元测试。

list/build.gradle.kts

tasks.withType<JavaCompile>().configureEach {
    javaCompiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(8)
    }
}

tasks.register<Test>("testsOn17") {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

list/build.gradle

tasks.withType(JavaCompile).configureEach {
    javaCompiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(8)
    }
}

tasks.register('testsOn17', Test) {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

此外，在 application 子项目中，我们添加了另一个 Java 执行任务，以使用 JDK 17 运行我们的应用程序。

application/build.gradle.kts

tasks.register<JavaExec>("runOn17") {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }

    classpath = sourceSets["main"].runtimeClasspath
    mainClass = application.mainClass
}

application/build.gradle

tasks.register('runOn17', JavaExec) {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }

    classpath = sourceSets.main.runtimeClasspath
    mainClass = application.mainClass
}

根据任务，JRE 可能就足够了，而对于其他任务（例如编译），则需要 JDK。默认情况下，如果已安装的 JDK 能够满足要求，Gradle 会优先选择它们而不是 JRE。

工具链工具提供程序可以从 javaToolchains 扩展中获取。

提供以下三种工具

JavaCompiler，它是 JavaCompile 任务使用的工具
JavaLauncher，它是 JavaExec 或 Test 任务使用的工具
JavadocTool，它是 Javadoc 任务使用的工具

与依赖于 Java 可执行文件或 Java home 的任务集成

任何可以配置 Java 可执行文件路径或 Java home 位置的任务都可以受益于工具链。

虽然您无法直接连接工具链工具，但它们都具有提供对其完整路径或其所属 Java 安装路径的访问权限的元数据。

例如，您可以按如下方式为任务配置 java 可执行文件

build.gradle.kts

val launcher = javaToolchains.launcherFor {
    languageVersion = JavaLanguageVersion.of(11)
}

tasks.sampleTask {
    javaExecutable = launcher.map { it.executablePath }
}

build.gradle

def launcher = javaToolchains.launcherFor {
    languageVersion = JavaLanguageVersion.of(11)
}

tasks.named('sampleTask') {
    javaExecutable = launcher.map { it.executablePath }
}

再举一个例子，您可以按如下方式为任务配置 *Java Home*

build.gradle.kts

val launcher = javaToolchains.launcherFor {
    languageVersion = JavaLanguageVersion.of(11)
}

tasks.anotherSampleTask {
    javaHome = launcher.map { it.metadata.installationPath }
}

build.gradle

def launcher = javaToolchains.launcherFor {
    languageVersion = JavaLanguageVersion.of(11)
}

tasks.named('anotherSampleTask') {
    javaHome = launcher.map { it.metadata.installationPath }
}

如果您需要特定工具（例如 Java 编译器）的路径，可以按如下方式获取

build.gradle.kts

val compiler = javaToolchains.compilerFor {
    languageVersion = JavaLanguageVersion.of(11)
}

tasks.yetAnotherSampleTask {
    javaCompilerExecutable = compiler.map { it.executablePath }
}

build.gradle

def compiler = javaToolchains.compilerFor {
    languageVersion = JavaLanguageVersion.of(11)
}

tasks.named('yetAnotherSampleTask') {
    javaCompilerExecutable = compiler.map { it.executablePath }
}

上面的示例使用具有 RegularFileProperty 和 DirectoryProperty 属性的任务，它们允许延迟配置。分别执行 launcher.get().executablePath、launcher.get().metadata.installationPath 或 compiler.get().executablePath 将为您提供给定工具链的完整路径，但请注意，这可能会急切地实现（并配置）工具链。

使用 Java 工具链

使用 Java 工具链允许 Gradle 自动下载和管理构建所需的 JDK 版本。它确保编译和执行都使用正确的 Java 版本。

您可以通过在 java 扩展块中声明 Java 语言版本来定义项目使用的工具链

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

现在执行构建（例如使用 gradle check）将为您和运行构建的其他人处理几件事

Gradle 配置所有编译、测试和 javadoc 任务以使用定义的工具链。
Gradle 检测本地安装的工具链。
Gradle 选择符合要求的工具链（例如，对于上面的示例，任何 Java 17 工具链）。
如果未找到匹配的工具链，Gradle 可以根据配置的工具链下载存储库自动下载匹配的工具链。

Java 插件及其定义的任务支持工具链。

对于 Groovy 插件，支持编译但尚未支持 Groovydoc 生成。对于 Scala 插件，支持编译和 Scaladoc 生成。

按供应商选择工具链

如果您的构建对使用的 JRE/JDK 有特定要求，您可能还需要定义工具链的供应商。JvmVendorSpec 包含 Gradle 识别的已知 JVM 供应商列表。优点是 Gradle 可以处理 JDK 版本之间 JVM 编码供应商信息方式的任何不一致。

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.ADOPTIUM
    }
}

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.ADOPTIUM
    }
}

如果您要定位的供应商不是已知供应商，您仍然可以将工具链限制为与可用工具链的 java.vendor 系统属性匹配的工具链。

以下代码片段使用过滤来包含可用工具链的子集。此示例仅包含其 java.vendor 属性包含给定匹配字符串的工具链。匹配以不区分大小写的方式完成。

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.matching("customString")
    }
}

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.matching("customString")
    }
}

选择支持 GraalVM 本机镜像的工具链

如果您的项目需要具有 GraalVM Native Image 功能的工具链，您可以配置规范以请求它

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
        nativeImageCapable = true
    }
}

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
        nativeImageCapable = true
    }
}

将该值保留未配置或设置为 false 不会根据本机镜像功能限制工具链选择。这意味着如果本机镜像兼容的 JDK 符合其他条件，则可以将其选中。

按虚拟机实现选择工具链

如果您的项目需要特定的实现，您也可以根据实现进行过滤。目前可供选择的实现有

VENDOR_SPECIFIC: 用作占位符，匹配任何供应商的任何实现（例如 hotspot、zulu 等）
J9: 仅匹配使用 OpenJ9/IBM J9 运行时引擎的虚拟机实现。

例如，要使用通过 AdoptOpenJDK 分发的 IBM JVM，您可以按以下示例所示指定过滤器。

build.gradle.kts

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.IBM
        implementation = JvmImplementation.J9
    }
}

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11)
        vendor = JvmVendorSpec.IBM
        implementation = JvmImplementation.J9
    }
}

Java 主版本、供应商（如果指定）和实现（如果指定）将被跟踪为编译和测试执行的输入。

配置工具链规范

Gradle 允许配置影响工具链选择的多个属性，例如语言版本或供应商。尽管这些属性可以独立配置，但配置必须遵循某些规则才能形成一个有效的规范。

在两种情况下，JavaToolchainSpec 被认为是有效的

未设置任何属性时，即规范是空的；
当设置了 languageVersion 时，可以选择后跟设置任何其他属性。

换句话说，如果指定了供应商或实现，则它们必须伴随语言版本。Gradle 区分配置语言版本的工具链规范和不配置语言版本的工具链规范。在大多数情况下，没有语言版本的规范将被视为选择当前构建的工具链。

自 Gradle 8.0 起，使用无效的 JavaToolchainSpec 实例会导致构建错误。

已安装工具链的自动检测

默认情况下，Gradle 会自动检测本地 JRE/JDK 安装，因此用户无需进一步配置。以下是 JVM 自动检测支持的常见包管理器、工具和位置列表。

JVM 自动检测知道如何与以下对象配合使用

操作系统特定位置：Linux、macOS、Windows
常用环境变量：JAVA_HOME
包管理器：Asdf-vm、Jabba、SDKMAN!
Maven 工具链规范
IntelliJ IDEA 安装

在所有检测到的 JRE/JDK 安装中，将根据工具链优先级规则选择一个。

无论您是使用工具链自动检测还是配置自定义工具链位置，不存在或没有 bin/java 可执行文件的安装都将被警告忽略，但它们不会生成错误。

如何禁用自动检测

要禁用自动检测，您可以使用 org.gradle.java.installations.auto-detect Gradle 属性

使用 -Porg.gradle.java.installations.auto-detect=false 启动 Gradle
或者将 org.gradle.java.installations.auto-detect=false 放入您的 gradle.properties 文件中。

自动配置

如果 Gradle 找不到与构建要求匹配的本地可用工具链，它可以自动下载一个（只要配置了工具链下载存储库；有关详细信息，请参阅相关部分）。Gradle 将下载的 JDK 安装在Gradle 用户主目录中。

Gradle 仅下载 GA 版本的 JDK。不支持下载早期访问版本。

一旦安装在Gradle 用户主目录中，配置的 JDK 就会成为自动检测可见的 JDK 之一，并且可以像系统上安装的任何其他 JDK 一样用于后续构建。

由于自动配置仅在自动检测未能找到匹配的 JDK 时才启动，因此自动配置只能下载新的 JDK，并且绝不涉及更新任何已安装的 JDK。任何自动配置的 JDK 都不会被自动配置重新访问和自动更新，即使它们有可用的较新次要版本。

工具链下载存储库

工具链下载存储库定义通过应用特定设置插件添加到构建中。有关编写此类插件的详细信息，请参阅工具链解析器插件页面。

Foojay 工具链插件是工具链解析器插件的一个示例，它基于 foojay Disco API。它甚至有一个约定变体，只需应用即可自动处理所有必要的配置

settings.gradle.kts

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention").version("1.0.0")
}

settings.gradle

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}

对于高级或高度特定的配置，应使用自定义工具链解析器插件。

通常，在应用工具链解析器插件时，它们提供的工具链下载解析器也需要配置。让我们用一个例子来说明。考虑构建应用了两个工具链解析器插件

一个是上面提到的 Foojay 插件，它通过其提供的 FoojayToolchainResolver 下载工具链。
另一个包含一个虚构的解析器，名为 MadeUpResolver。

以下示例通过设置文件中的 toolchainManagement 块在构建中使用这些工具链解析器

settings.gradle.kts

toolchainManagement {
    jvm { (1)
        javaRepositories {
            repository("foojay") { (2)
                resolverClass = org.gradle.toolchains.foojay.FoojayToolchainResolver::class.java
            }
            repository("made_up") { (3)
                resolverClass = MadeUpResolver::class.java
                credentials {
                    username = "user"
                    password = "password"
                }
                authentication {
                    create<DigestAuthentication>("digest")
                } (4)
            }
        }
    }
}

settings.gradle

toolchainManagement {
    jvm { (1)
        javaRepositories {
            repository('foojay') { (2)
                resolverClass = org.gradle.toolchains.foojay.FoojayToolchainResolver
            }
            repository('made_up') { (3)
                resolverClass = MadeUpResolver
                credentials {
                    username = "user"
                    password = "password"
                }
                authentication {
                    digest(BasicAuthentication)
                } (4)
            }
        }
    }
}

1	在 `toolchainManagement` 块中，`jvm` 块包含 Java 工具链的配置。
2	`javaRepositories` 块定义了命名的 Java 工具链存储库配置。使用 `resolverClass` 属性将这些配置链接到插件。
3	工具链声明顺序很重要。Gradle 从提供匹配的第一个存储库下载，从列表中的第一个存储库开始。
4	您可以配置工具链存储库，并使用与依赖管理相同的身份验证和授权选项。

toolchainManagement 中的 jvm 块仅在应用工具链解析器插件后才会解析。

查看和调试工具链

Gradle 可以显示所有检测到的工具链列表，包括它们的元数据。

例如，要显示项目的所有工具链，请运行

gradle -q javaToolchains

gradle -q javaToolchains 的输出

> gradle -q javaToolchains

 + Options
     | Auto-detection:     Enabled
     | Auto-download:      Enabled

 + AdoptOpenJDK 1.8.0_242
     | Location:           /Users/username/myJavaInstalls/8.0.242.hs-adpt/jre
     | Language Version:   8
     | Vendor:             AdoptOpenJDK
     | Architecture:       x86_64
     | Is JDK:             false
     | Detected by:        Gradle property 'org.gradle.java.installations.paths'

 + Microsoft JDK 16.0.2+7
     | Location:           /Users/username/.sdkman/candidates/java/16.0.2.7.1-ms
     | Language Version:   16
     | Vendor:             Microsoft
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        SDKMAN!

 + OpenJDK 15-ea
     | Location:           /Users/user/customJdks/15.ea.21-open
     | Language Version:   15
     | Vendor:             AdoptOpenJDK
     | Architecture:       x86_64
     | Is JDK:             true
     | Detected by:        environment variable 'JDK16'

 + Oracle JDK 1.7.0_80
     | Location:           /Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home/jre
     | Language Version:   7
     | Vendor:             Oracle
     | Architecture:       x86_64
     | Is JDK:             false
     | Detected by:        MacOS java_home

这有助于调试构建可用的工具链、它们是如何检测到的以及 Gradle 了解这些工具链的哪些元数据。

禁用自动配置

要禁用自动配置，您可以使用 org.gradle.java.installations.auto-download Gradle 属性

使用 -Porg.gradle.java.installations.auto-download=false 启动 Gradle
或者将 org.gradle.java.installations.auto-download=false 放入 gradle.properties 文件中。

禁用自动配置后，请确保构建文件中指定的 JRE/JDK 版本已在本地安装。然后，停止 Gradle 守护进程，以便为下一次构建重新初始化。您可以使用 ./gradlew --stop 命令停止守护进程。

移除自动配置的工具链

当需要移除自动配置的工具链时，请移除Gradle 用户主目录中 /jdks 目录下的相关工具链。

Gradle Daemon 缓存有关项目的信息，包括工具链路径或版本等配置详细信息。项目工具链配置的更改可能只有在 Gradle Daemon 重启后才会生效。建议停止 Gradle Daemon 以确保 Gradle 为后续构建更新配置。

自定义工具链位置

如果自动检测本地工具链不足或已禁用，您可以通过其他方式让 Gradle 了解已安装的工具链。

如果您的设置已提供指向已安装 JVM 的环境变量，您还可以让 Gradle 知道要考虑哪些环境变量。假设环境变量 JDK8 和 JRE17 指向有效的 Java 安装，以下说明 Gradle 解析这些环境变量并在查找匹配工具链时考虑这些安装。

org.gradle.java.installations.fromEnv=JDK8,JRE17

此外，您可以使用 org.gradle.java.installations.paths 属性提供以逗号分隔的特定安装路径列表。例如，在您的 gradle.properties 中使用以下内容将让 Gradle 知道在检测工具链时要查找哪些目录。Gradle 会将这些目录视为可能的安装，但不会进入任何嵌套目录。

org.gradle.java.installations.paths=/custom/path/jdk1.8,/shared/jre11

Gradle 不会优先考虑自定义工具链而不是自动检测的工具链。如果在构建中启用自动检测，自定义工具链会扩展工具链位置集。Gradle 根据优先级规则选择工具链。

工具链安装优先级

Gradle 将对所有匹配构建工具链规范的 JDK/JRE 安装进行排序，并选择第一个。排序基于以下规则

当前运行 Gradle 的安装优先于任何其他安装
JDK 安装优先于 JRE 安装
某些供应商优先于其他供应商；它们的顺序（从最高优先级到最低优先级）
1. ADOPTIUM
2. ADOPTOPENJDK
3. AMAZON
4. APPLE
5. AZUL
6. BELLSOFT
7. GRAAL_VM
8. HEWLETT_PACKARD
9. IBM
10. JETBRAINS
11. MICROSOFT
12. ORACLE
13. SAP
14. TENCENT
15. 其他一切
更高的主要版本优先于较低的版本
更高的次要版本优先于较低的版本
安装路径根据其字典顺序优先（用于确定性地决定相同类型、相同供应商和相同版本的安装之间的最后手段标准）

所有这些规则都作为多级排序标准按所示顺序应用。让我们用一个例子来说明。一个工具链规范请求 Java 17 版本。Gradle 检测到以下匹配的安装

Oracle JRE v17.0.1
Oracle JDK v17.0.0
Microsoft JDK 17.0.0
Microsoft JRE 17.0.1
Microsoft JDK 17.0.1

假设 Gradle 在除 17 以外的主要 Java 版本上运行。否则，该安装将具有优先级。

当我们应用上述规则对该集合进行排序时，我们将得到以下顺序

Microsoft JDK 17.0.1
Microsoft JDK 17.0.0
Oracle JDK v17.0.0
Microsoft JRE v17.0.1
Oracle JRE v17.0.1

Gradle 优先选择 JDK 而不是 JRE，所以 JRE 排在最后。Gradle 优先选择 Microsoft 供应商而不是 Oracle，所以 Microsoft 安装排在第一位。Gradle 优先选择更高的版本号，所以 JDK 17.0.1 排在 JDK 17.0.0 之前。

所以 Gradle 选择此顺序中的第一个匹配项：Microsoft JDK 17.0.1。

插件作者工具链

创建使用工具链的插件或任务时，提供合理的默认值并允许用户覆盖它们至关重要。

对于 JVM 项目，通常可以安全地假设 java 插件已应用于项目。java 插件会自动应用于核心 Groovy 和 Scala 插件，以及 Kotlin 插件。在这种情况下，使用通过 java 扩展定义的工具链作为工具属性的默认值是合适的。这样，用户只需在项目级别配置工具链一次。

以下示例展示了如何将默认工具链用作约定，同时允许用户为每个任务单独配置工具链。

build.gradle.kts

abstract class CustomTaskUsingToolchains : DefaultTask() {

    @get:Nested
    abstract val launcher: Property<JavaLauncher> (1)

    init {
        val toolchain = project.extensions.getByType<JavaPluginExtension>().toolchain (2)
        val defaultLauncher = javaToolchainService.launcherFor(toolchain) (3)
        launcher.convention(defaultLauncher) (4)
    }

    @TaskAction
    fun showConfiguredToolchain() {
        println(launcher.get().executablePath)
        println(launcher.get().metadata.installationPath)
    }

    @get:Inject
    protected abstract val javaToolchainService: JavaToolchainService
}

build.gradle

abstract class CustomTaskUsingToolchains extends DefaultTask {

    @Nested
    abstract Property<JavaLauncher> getLauncher() (1)

    CustomTaskUsingToolchains() {
        def toolchain = project.extensions.getByType(JavaPluginExtension.class).toolchain (2)
        Provider<JavaLauncher> defaultLauncher = getJavaToolchainService().launcherFor(toolchain) (3)
        launcher.convention(defaultLauncher) (4)
    }

    @TaskAction
    def showConfiguredToolchain() {
        println launcher.get().executablePath
        println launcher.get().metadata.installationPath
    }

    @Inject
    protected abstract JavaToolchainService getJavaToolchainService()
}

1	我们在任务上声明一个 `JavaLauncher` 属性。该属性必须标记为 `@Nested` 输入，以确保任务响应工具链更改。
2	我们从 `java` 扩展中获取工具链规范以用作默认值。
3	使用 `JavaToolchainService`，我们获取一个与工具链匹配的 `JavaLauncher` 提供程序。
4	最后，我们将启动器提供程序作为我们属性的约定。

在应用了 java 插件的项目中，我们可以按如下方式使用该任务

build.gradle.kts

plugins {
    java
}

java {
    toolchain { (1)
        languageVersion = JavaLanguageVersion.of(8)
    }
}

tasks.register<CustomTaskUsingToolchains>("showDefaultToolchain") (2)

tasks.register<CustomTaskUsingToolchains>("showCustomToolchain") {
    launcher = javaToolchains.launcherFor { (3)
        languageVersion = JavaLanguageVersion.of(17)
    }
}

build.gradle

plugins {
    id 'java'
}

java {
    toolchain { (1)
        languageVersion = JavaLanguageVersion.of(8)
    }
}

tasks.register('showDefaultToolchain', CustomTaskUsingToolchains) (2)

tasks.register('showCustomToolchain', CustomTaskUsingToolchains) {
    launcher = javaToolchains.launcherFor { (3)
        languageVersion = JavaLanguageVersion.of(17)
    }
}

1	`java` 扩展上定义的工具链默认用于解析启动器。
2	没有额外配置的自定义任务将使用默认的 Java 8 工具链。
3	其他任务通过使用 `javaToolchains` 服务选择不同的工具链来覆盖启动器的值。

当任务需要访问工具链而没有应用 java 插件时，可以直接使用工具链服务。如果向服务提供未配置的工具链规范，它将始终返回运行 Gradle 的工具链的工具提供程序。这可以通过在请求工具时传递一个空 lambda 来实现：javaToolchainService.launcherFor({})。

您可以在编写任务文档中找到有关定义自定义任务的更多详细信息。

工具链限制

当 Gradle 在针对 musl（C 标准库的替代实现）编译的 JVM 中运行时，它可能会错误地检测工具链。针对 musl 编译的 JVM 有时会覆盖 LD_LIBRARY_PATH 环境变量以控制动态库解析。这可能会影响 Gradle 启动的派生 Java 进程，导致意外行为。

因此，不建议在具有 musl 库的环境中使用多个 Java 工具链。大多数 Alpine 发行版都是这种情况——请考虑改用其他发行版，例如 Ubuntu。如果您正在使用单个工具链（运行 Gradle 的 JVM）来构建和运行应用程序，则可以安全地忽略此限制。

此页面有帮助吗？