Android 构建中的 Java 版本

无论您的源代码是用 Java、Kotlin 还是两者编写，您都需要在几个地方为构建选择 JDK 或 Java 语言版本。

词汇表

Java 开发工具包 (JDK)

The Java 开发工具包 (JDK) 包含

• 工具，例如编译器、分析器和归档创建器。这些工具在构建过程中幕后使用，以创建您的应用程序。
• 包含 API 的库，您可以从 Kotlin 或 Java 源代码中调用这些 API。请注意，并非所有功能都可以在 Android 上使用。
• Java 虚拟机 (JVM)，一个解释器，用于执行 Java 应用程序。您使用 JVM 运行 Android Studio IDE 和 Gradle 构建工具。JVM 不在 Android 设备或模拟器上使用。

JetBrains 运行时 (JBR)

The JetBrains 运行时 (JBR) 是一个增强的 JDK，与 Android Studio 一起发布。它包含一些针对 Studio 和相关的 JetBrains 产品进行的优化，但也可以用于运行其他 Java 应用程序。

我如何选择 JDK 来运行 Android Studio？

我们建议您使用 JBR 来运行 Android Studio。它与 Android Studio 一起部署并用于测试 Android Studio，并且包含增强功能以实现最佳 Android Studio 使用体验。为了确保这一点，请勿设置 STUDIO_JDK 环境变量。

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

1. STUDIO_JDK 环境变量
2. studio.jdk 目录（在 Android Studio 分发版中）
3. jbr 目录（JetBrains 运行时），在 Android Studio 分发版中。推荐。
4. JDK_HOME 环境变量
5. JAVA_HOME 环境变量
6. java 可执行文件，位于 PATH 环境变量中

我如何选择哪个 JDK 运行我的 Gradle 构建？

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

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

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

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

Android Studio 中的 Gradle JDK 配置

要修改现有项目的 Gradle JDK 配置，请从文件（或 macOS 上的Android Studio）> 设置 > 构建、执行、部署 > 构建工具 > Gradle中打开 Gradle 设置。Gradle JDK下拉菜单包含以下选项供选择

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

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

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

• JAVA_HOME：使用与之同名的环境变量
• GRADLE_LOCAL_JAVA_HOME：使用 .gradle/config.properties 文件中的 java.home 属性，该属性默认为 JetBrains Runtime。

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

确保选择一个 JDK 版本，该版本高于或等于 Gradle 构建中使用的插件所使用的 JDK 版本。要确定 Android Gradle 插件 (AGP) 的最低所需 JDK 版本，请参阅 发行说明 中的兼容性表。

例如，Android Gradle 插件版本 8.x 需要 JDK 17。如果您尝试使用较早版本的 JDK 运行使用它的 Gradle 构建，它会报告类似以下的消息

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/jdk11
      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 定义了许多 Java 库函数的实现，作为其可用 API 的一部分。compileSdk 属性指定在编译 Kotlin 或 Java 源代码时要使用的 Android SDK 版本。

android {
    ...
    compileSdk = 33
}

android {
    ...
    compileSdk 33
}

每个版本的 Android 都支持特定版本的 JDK 及其可用 Java API 的子集。如果您使用了一个在 compileSdk 中可用但在指定的 minSdk 中不可用的 Java API，则可以通过称为 反糖化 的过程在较早版本的 Android 中使用该 API。有关支持的 API，请参阅 通过反糖化可用的 Java 11+ API。

使用此表确定每个 Android API 支持哪些 Java 版本，以及在何处查找有关哪些 Java API 可用的详细信息。

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

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

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

要创建更一致的构建，您可以显式指定 Java 工具链版本。指定此选项

• 在运行构建的系统上找到一个兼容的 JDK。
  • 如果没有兼容的 JDK（并且定义了工具链解析器），则下载一个 JDK。
• 为来自源代码的调用公开工具链 Java API。
• 使用其 Java 语言版本编译 Java 源代码。
• 为 sourceCompatibility 和 targetCompatibility 提供默认值。

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

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

像这样指定 Java 工具链版本

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

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

如果您的源代码是 Kotlin、Java 或二者的混合，此方法都有效。

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

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

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

如果未指定，则默认为用于运行 Gradle 的 Java 工具链 或 JDK。我们建议您始终显式指定工具链（首选）或 sourceCompatibility。

在模块的 build.gradle(.kts) 文件中指定 sourceCompatibility。

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

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

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

Kotlin 的一些功能在添加等效的 Java 功能之前就已经存在。早期的 Kotlin 编译器不得不创建自己的方法来表示这些 Kotlin 功能。其中一些功能后来被添加到 Java 中。使用较新的 jvmTarget 级别，Kotlin 编译器可能会直接使用 Java 功能，这可能会带来更好的性能。

targetCompatibility 默认为与 sourceCompatibility 相同的值，但如果指定，则必须大于或等于 sourceCompatibility。

jvmTarget 默认为 工具链 版本。

不同版本的 Android 支持不同的 Java 版本。您可以通过增加 targetCompatibility 和 jvmTarget 来利用额外的 Java 功能，但这可能会迫使您也增加 最低 Android SDK 版本 以确保该功能可用。

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

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