Android 建構作業中的 Java 版本

無論原始碼是以 Java 和/或 Kotlin 編寫，您必須在幾個地方選擇建構的 JDK 或 Java 語言版本。

詞彙解釋

Java Development Kit (JDK)

Java Development Kit (JDK) 包含：

• 包括編譯器、分析器和封存建立者等工具。 在建構期間，這些資訊可用於建立應用程式。
• 包含可透過 Kotlin 或 Java 原始碼呼叫的 API 的程式庫。請注意，Android 並未提供所有函式。
• Java 虛擬機器 (JVM) 是執行 Java 應用程式的解譯器。您可以使用 JVM 執行 Android Studio IDE 和 Gradle 建構工具。Android 裝置或模擬器不會使用 JVM。

JetBrains Runtime (JBR)

JetBrains Runtime (JBR) 是與 Android Studio 一起發布的增強版 JDK。包含多項最佳化設定，以便在 Studio 和相關 JetBrains 產品中使用，但也能用於執行其他 Java 應用程式。

如何選擇 JDK 來執行 Android Studio？

建議您使用 JBR 執行 Android Studio。此版本會部署並用於測試 Android Studio，並提供有助提升 Android Studio 使用體驗的強化功能。為確保這一點，不要設定 STUDIO_JDK 環境變數。

Android Studio 的開機指令碼會以下列順序尋找 JVM：

1. STUDIO_JDK 環境變數
2. studio.jdk 目錄 (位於 Android Studio 發行版本中)
3. jbr 目錄 (JetBrains Runtime)。推薦影片。
4. JDK_HOME 環境變數
5. JAVA_HOME 環境變數
6. PATH 環境變數中的 java 執行檔

如何選擇用來執行 Gradle 版本的 JDK？

如果您使用 Android Studio 中的按鈕執行 Gradle，則 Android Studio 設定中設定的 JDK 會用於執行 Gradle。如果您在 Android Studio 內部或外部的終端機中執行 Gradle，則 JAVA_HOME 環境變數 (如有設定) 會決定執行 Gradle 指令碼的 JDK。如未設定 JAVA_HOME，則會使用 PATH 環境變數的 java 指令。

為取得最一致的結果，請務必將 JAVA_HOME 環境變數和 Android Studio 中的 Gradle JDK 設定設為同一個 JDK。

注意： 如果您在 Android Studio 終端機中以滑鼠右鍵按一下，並使用 IDE 選取「Run 醒目顯示的指令」來執行 Gradle 指令，則系統會使用 Android Studio 設定中的 JDK，而非 JAVA_HOME。

執行建構作業時，Gradle 會建立稱為「Daemon」的程序，以執行實際建構作業。只要建構作業使用相同的 JDK 和 Gradle 版本，就可以重複使用此程序。重複使用 Daemon 可縮短啟動新 JVM 及初始化建構系統的時間。

如果您使用不同的 JDK 或 Gradle 版本開始建構，則會建立額外的 Daemon，佔用更多 CPU 和記憶體。

提示： 如果可能同時處理多項專案，請在 gradle-wrapper.properties 檔案中指定相同的 Gradle 版本，以減少建立的 Gradle Daemon 數量。

Android Studio 中的 Gradle JDK 設定

如要修改現有專案的 Gradle JDK 設定，請依序前往「File」 (或在 macOS 為「Android Studio」) 開啟 Gradle 設定，然後依序點選「Settings」>「Build, Execution, Deployment」>「Build Tools」>「Gradle」。「Gradle JDK」下拉式選單包含以下選項：

• 巨集，例如 JAVA_HOME 和 GRADLE_LOCAL_JAVA_HOME
• JDK 資料表項目，格式為 vendor-version，例如儲存在 Android 設定檔中的 jbr-17
• 下載 JDK
• 新增特定 JDK
• 從作業系統的預設 JDK 安裝目錄本機偵測到的 JDK

所選選項會儲存在專案 .idea/gradle.xml 檔案的 gradleJvm 選項中，而其 JDK 路徑解析則用於在透過 Android Studio 啟動時執行 Gradle。

圖 1：Android Studio 中的 Gradle JDK 設定。

巨集會啟用動態專案的 JDK 路徑選取功能：

• JAVA_HOME：使用同名的環境變數
• GRADLE_LOCAL_JAVA_HOME：使用 .gradle/config.properties 檔案中的 java.home 屬性，該屬性預設為 JetBrains Runtime。

所選 JDK 會在編輯建構指令碼和原始碼時，用來執行 Gradle 版本並解析 JDK API 參照。請注意，編輯及建構原始碼時，指定的 compileSdk 會進一步限制可用的 Java 符號。

注意： 在大部分情況下，建議您使用 GRADLE_LOCAL_JAVA_HOME，這是新建專案的預設選項。這樣您無須先開啟專案，就能定義專案專屬的 JDK。

選取的 JDK 版本必須高於或等於您在 Gradle 版本中使用的外掛程式所使用的 JDK 版本。如要判斷 Android Gradle 外掛程式 (AGP) 所需的 JDK 最低版本，請參閱版本資訊中的相容性表格。

舉例來說，Android Gradle 外掛程式 8.x 版需要 JDK 17。如果您嘗試執行的 Gradle 版本與舊版 JDK 搭配使用，系統會回報如下訊息：

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 版本。

Kotlin

android {
    ...
    compileSdk = 33
}

Groovy

android {
    ...
    compileSdk 33
}

每個 Android 版本都支援特定版本的 JDK，以及一部分的可用 Java API。如果您使用的 Java API 於指定 minSdk 中未提供，在舊版 Android 中可透過脫糖程序使用 API。compileSdk如要瞭解支援的 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 版本，建構的結果可能會有所不同。

如要建立更一致的建構，您可以明確指定 Java 工具鍊版本。指定：

• 在執行建構的系統上找出相容的 JDK。
  • 如果沒有相容的 JDK (且已定義工具鍊解析器)，請下載一個。
• 為來自原始碼的呼叫公開工具鍊 Java API。
• 使用 Java 語言版本編譯 Java 原始碼。
• sourceCompatibility 和 targetCompatibility 的提供預設值。

建議您一律指定 Java 工具鍊，並確保已安裝指定的 JDK，或在建構作業中新增工具鍊解析器。

無論原始碼是以 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 來源。

如未指定，系統會使用預設使用 Java 工具鍊或執行 Gradle 的 JDK。建議您一律明確指定工具鍊 (建議選項) 或 sourceCompatibility。

在模組的 build.gradle(.kts) 檔案中指定 sourceCompatibility。

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

Groovy

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

注意： 自 Android Studio Giraffe 以來，當您匯入專案時，sourceCompatibility 選項也會做為 IDE 程式碼輔助與 Lint 編寫 Java 來源時的預設選項。部分 Java 語言功能需要程式庫支援，且不適用於 Android。compileSdk 選項會決定可用的程式庫。其他功能 (例如切換運算式) 只需要 Java 編譯器，即可在 Android 上運作。

編譯 Kotlin 或 Java 來源時，可以使用哪些 Java 二進位檔功能？

指定 targetCompatibility 和 jvmTarget 可分別決定產生已編譯 Java 和 Kotlin 來源位元碼時使用的 Java 類別格式版本。

在新增對等的 Java 功能之前，就存在部分 Kotlin 功能。早期 Kotlin 編譯器必須建立自己的方式來表示這些 Kotlin 功能。其中部分功能稍後新增至 Java。隨著之後的 jvmTarget 層級，Kotlin 編譯器可能會直接使用 Java 功能，這可能會提升效能。

targetCompatibility 預設為與 sourceCompatibility 相同的值，但如有指定，其值必須大於或等於 sourceCompatibility。

jvmTarget 預設為工具鍊版本。

不同 Android 版本支援不同版本的 Java。您可以增加 targetCompatibility 和 jvmTarget 來運用其他 Java 功能，但這可能會導致您還需提高 Android SDK 最低版本，確保可以使用該功能。

Kotlin

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

Groovy

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