此页面由 Cloud Translation API 翻译。

Android build 中的 Java 版本

无论您的源代码是用 Java 还是 Kotlin 编写的，您都必须在多个位置为 build 选择 JDK 或 Java 语言版本。

Gradle build 中的 JDK 关系概览 — **图 1.** 构建中的 JDK 关系

术语库

Java 开发套件 (JDK)

Java 开发套件 (JDK) 包含：

工具，例如编译器、性能分析器和归档创建工具。这些文件会在构建过程中在后台使用，以创建您的应用。
包含您可以从 Kotlin 或 Java 源代码调用的 API 的库。请注意，部分功能仅适用于 Android 设备。
Java 虚拟机 (JVM)，一种用于执行 Java 应用的解释器。您可以使用 JVM 运行 Android Studio IDE 和 Gradle 构建工具。JVM 不会在 Android 设备或模拟器上使用。

JetBrains 运行时 (JBR)

JetBrains Runtime (JBR) 是一种增强型 JDK，与 Android Studio 一起分发。它包含一些可在 Studio 和相关 JetBrains 产品中使用的优化，但也可以用于运行其他 Java 应用。

如何选择用于运行 Android Studio 的 JDK？

我们建议您使用 JBR 运行 Android Studio。该插件随 Android Studio 一起部署并用于测试 Android Studio，并包含一些增强功能，可确保最佳 Android Studio 使用体验。为此，请勿设置 STUDIO_JDK 环境变量。

Android Studio 的启动脚本会按以下顺序查找 JVM：

STUDIO_JDK 环境变量
studio.jdk 目录（在 Android Studio 发行版中）
Android Studio 发行版中的 jbr 目录（JetBrains 运行时）。推荐。
JDK_HOME 环境变量
JAVA_HOME 环境变量
PATH 环境变量中的 java 可执行文件

如何选择运行 Gradle build 的 JDK？

如果您使用 Android Studio 中的按钮运行 Gradle，则 Android Studio 设置中设置的 JDK 将用于运行 Gradle。如果您在终端（Android Studio 内或外）中运行 Gradle，则 JAVA_HOME 环境变量（如果已设置）决定了哪个 JDK 运行 Gradle 脚本。如果未设置 JAVA_HOME，则会对 PATH 环境变量使用 java 命令。

为了获得最一致的结果，请务必将 JAVA_HOME 环境变量和 Android Studio 中的 Gradle JDK 配置设置为同一 JDK。

运行 build 时，Gradle 会创建一个名为“守护程序”的进程来执行实际 build。只要 build 使用的是相同的 JDK 和 Gradle 版本，就可以重复使用此流程。重复使用守护程序可缩短启动新 JVM 和初始化构建系统的时间。

如果您使用不同的 JDK 或 Gradle 版本启动 build，系统会创建其他守护程序，从而消耗更多 CPU 和内存。

Android Studio 中的 Gradle JDK 配置

如需修改现有项目的 Gradle JDK 配置，请依次前往 File（或在 macOS 上依次前往 Android Studio） > Settings > Build, Execution, Deployment > Build Tools > Gradle，打开 Gradle 设置。Gradle JDK 下拉菜单包含以下可供选择的选项：

宏（例如 JAVA_HOME 和 GRADLE_LOCAL_JAVA_HOME）
vendor-version 格式的 JDK 表条目（例如 jbr-17），存储在 Android 配置文件中
下载 JDK
添加特定 JDK
从操作系统的默认 JDK 安装目录本地检测到的 JDK

所选选项存储在项目的 .idea/gradle.xml 文件中的 gradleJvm 选项中，其 JDK 路径解析用于在通过 Android Studio 启动时运行 Gradle。

**图 2.** Android Studio 中的 Gradle JDK 设置。

这些宏支持动态选择项目 JDK 路径：

JAVA_HOME：使用同名的环境变量
GRADLE_LOCAL_JAVA_HOME：使用 .gradle/config.properties 文件中的 java.home 属性，默认为 JetBrains 运行时。

所选的 JDK 用于运行 Gradle build，并在修改 build 脚本和源代码时解析 JDK API 引用。请注意，在修改和构建源代码时，指定的 compileSdk 会进一步限制可用的 Java 符号。

请务必选择高于或等于您在 Gradle build 中使用的插件所使用的 JDK 版本的 JDK 版本。如需确定 Android Gradle 插件 (AGP) 的最低要求 JDK 版本，请参阅版本说明中的兼容性表格。

例如，Android Gradle 插件版本 8.x 需要 JDK 17。如果您尝试运行使用较低版本 JDK 的 Gradle build，则会收到如下消息：

An exception occurred applying plugin request [id: 'com.android.application']
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in /usr/local/buildtools/java/jdk
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

我可以在 Java 或 Kotlin 源代码中使用哪些 Java API？

Android 应用可以使用 JDK 中定义的部分 API，但不能使用所有 API。Android SDK 在其可用 API 中定义了许多 Java 库函数的实现。compileSdk 属性用于指定在编译 Kotlin 或 Java 源代码时要使用的 Android SDK 版本。

Kotlin

android {
    ...
    compileSdk = 33
}

Groovy

android {
    ...
    compileSdk 33
}

每个版本的 Android 都支持特定版本的 JDK 以及其可用 Java API 的一部分。如果您使用的 Java API 在 compileSdk 中可用，但在指定的 minSdk 中不可用，则您或许可以通过称为脱糖的流程在较低版本的 Android 中使用该 API。如需了解受支持的 API，请参阅通过脱糖提供的 Java 11 及更高版本 API。

您可以使用此表格确定每个 Android API 支持哪个 Java 版本，以及在哪里可以详细了解可用的 Java API。

Android	Java	支持的 API 和语言功能
14（API 34）	17	核心库
13（API 33）	11	核心库
12（API 32）	11	Java API
11 及更低版本		Android 版本

哪个 JDK 会编译我的 Java 源代码？

Java 工具链 JDK 包含用于编译任何 Java 源代码的 Java 编译器。此 JDK 还会在构建期间运行 javadoc 和单元测试。

工具链默认为用于运行 Gradle 的 JDK。如果您使用默认设置并在不同的计算机（例如本地计算机和单独的持续集成服务器）上运行构建，那么如果使用不同的 JDK 版本，构建结果可能会有所不同。

如需创建更一致的 build，您可以明确指定 Java 工具链版本。指定此属性：

在运行 build 的系统上查找兼容的 JDK。
- 如果不存在兼容的 JDK（并且已定义工具链解析器），则下载一个。
公开工具链 Java API，以便从源代码进行调用。
使用 Java 语言版本编译 Java 源代码。
sourceCompatibility 和 targetCompatibility 的默认值。

我们建议您始终指定 Java 工具链，并确保已安装指定的 JDK，或者向 build 中添加工具链解析器。

无论您的源代码是用 Java 还是 Kotlin 编写的，您都可以指定工具链。在模块的 build.gradle(.kts) 文件的顶层指定工具链。

指定 Java 工具链版本，如下所示：

Kotlin

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

Groovy

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

如果您的源代码是 Kotlin、Java 或两者的混合，此方法适用。

工具链 JDK 版本可以与用于运行 Gradle 的 JDK 相同，但请注意，它们的用途不同。

我可以在 Java 源代码中使用哪些 Java 语言源代码功能？

sourceCompatibility 属性决定了在编译 Java 源代码期间可用的 Java 语言功能。它不会影响 Kotlin 源代码。

在模块的 build.gradle(.kts) 文件中指定 sourceCompatibility，如下所示：

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

Groovy

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

如果未指定，此属性默认为 Java 工具链版本。如果您不使用 Java 工具链，则默认使用 Android Gradle 插件选择的版本（例如 Java 8 或更高版本）。

在编译 Kotlin 或 Java 源代码时，可以使用哪些 Java 二进制功能？

targetCompatibility 和 jvmTarget 属性分别决定为编译的 Java 和 Kotlin 源代码生成字节码时使用的 Java 类格式版本。

在添加等效的 Java 功能之前，就已经存在一些 Kotlin 功能。早期的 Kotlin 编译器必须自行创建表示这些 Kotlin 功能的方法。其中一些功能后来被添加到了 Java 中。在较高版本的 jvmTarget 中，Kotlin 编译器可能会直接使用 Java 功能，这可能会带来更好的性能。

不同版本的 Android 支持不同的 Java 版本。您可以通过提高 targetCompatibility 和 jvmTarget 来使用其他 Java 功能，但这可能会迫使您也提高最低 Android SDK 版本，以确保该功能可用。

请注意，targetCompatibility 必须大于或等于 sourceCompatibility。在实践中，sourceCompatibility、targetCompatibility 和 jvmTarget 通常应使用相同的值。您可以按如下方式进行设置：

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

Groovy

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget '17'
    }
}

如果未指定，这些属性默认为 Java 工具链版本。如果您未使用 Java 工具链，则默认值可能会有所不同，并导致构建问题。因此，我们建议您始终明确指定这些值或使用 Java 工具链。