Android Gradle 外掛程式版本資訊

JCenter 存放區已於 2021 年 3 月 31 日設為唯讀狀態。詳情請參閱 JCenter 服務更新內容。

Android Studio 建構系統以 Gradle 為基礎，Android Gradle 外掛程式則加入了建構 Android 應用程式專用的功能。雖然 Android 外掛程式通常會與 Android Studio 同步更新，但外掛程式 (和 Gradle 系統的其他內容) 可獨立於 Android Studio 之外執行，也可另外更新。

本頁面將說明如何讓 Gradle 工具保持最新狀態，並介紹近期更新項目。如要查看過往 Android Gradle 外掛程式版本的版本資訊，請參閱過往的版本資訊。

如要針對 Android Gradle 外掛程式即將推出的破壞性變更查看相關的概略摘要，請參閱 Android Gradle 外掛程式發展藍圖。

若想進一步瞭解如何使用 Gradle 設定 Android 版本，可參閱下列頁面的說明：

如要進一步瞭解 Gradle 建構系統，請參閱 Gradle 使用手冊。

更新 Android Gradle 外掛程式

更新 Android Studio 時，系統可能會要求自動將 Android Gradle 外掛程式更新為可供使用的最新版本。您可以選擇接受更新，也可根據專案的版本需求手動指定版本。

如要指定外掛程式版本，請在 Android Studio 中依序前往「File」>「Project Structure」>「Project」選單，或者在頂層 build.gradle 檔案內操作。這個外掛程式版本會套用到該 Android Studio 專案內建構的所有模組。以下範例會透過 build.gradle 檔案將外掛程式設為 7.4.1 版：

Groovy

plugins {
    id 'com.android.application' version '7.4.1' apply false
    id 'com.android.library' version '7.4.1' apply false
    id 'org.jetbrains.kotlin.android' version '1.5.31' apply false
}

Kotlin

plugins {
    id("com.android.application") version "7.4.1" apply false
    id("com.android.library") version "7.4.1" apply false
    id("org.jetbrains.kotlin.android") version "1.5.31" apply false
}

注意：請勿在版本編號中使用動態依附元件，例如 'com.android.tools.build:gradle:2.+'。使用這項功能可能會造成非預期的版本更新情形，並導致難以解析版本差異。

如果您尚未下載指定的外掛程式版本，當您下次建構專案，或在 Android Studio 選單列中依序點選「File」>「Sync Project with Gradle Files」時，Gradle 就會下載該版本。

更新 Gradle

更新 Android Studio 時，系統可能會要求同時將 Gradle 更新為可供使用的最新版本。您可以選擇接受更新，也可根據專案的版本需求手動指定版本。

下表列出各個 Android Gradle 外掛程式版本所需的 Gradle 版本。為獲得最佳效能，請務必使用最新版本的 Gradle 及外掛程式。

外掛程式版本	Gradle 最低版本需求
8.1	8.0
8.0	8.0
7.4	7.5
7.3	7.4
7.2	7.3.3
7.1	7.2
7.0	7.0
4.2.0+	6.7.1

較舊版本

外掛程式版本	所需 Gradle 版本
4.1.0+	6.5+
4.0.0+	6.1.1+
3.6.0 - 3.6.4	5.6.4+
3.5.0 - 3.5.4	5.4.1+
3.4.0 - 3.4.3	5.1.1+
3.3.0 - 3.3.3	4.10.1+
3.2.0 - 3.2.1	4.6+
3.1.0+	4.4+
3.0.0+	4.1+
2.3.0+	3.3+
2.1.3 - 2.2.3	2.14.1 - 3.5
2.0.0 - 2.1.2	2.10 - 2.13
1.5.0	2.2.1 - 2.13
1.2.0 - 1.3.1	2.2.1 - 2.9
1.0.0 - 1.1.3	2.2.1 - 2.3

如要指定 Gradle 版本，請在 Android Studio 中依序前往「File」>「Project Structure」>「Project」選單，或者使用使用指令列來更新 Gradle 版本。建議您使用 Gradle 包裝函式指令列工具，此工具會更新 gradlew 指令碼。以下範例會使用 Gradle 包裝函式來將 Gradle 版本設定為 7.5.1。請注意，您必須執行這個指令「兩次」，才能升級 Gradle 和 Gradle 包裝函式 (詳情請參閱「升級 Gradle 包裝函式」一文)。

gradle wrapper --gradle-version 7.5.1

不過，這個方法在某些情況下可能會失敗，例如您剛更新了 AGP，而更新後的版本不再符合目前 Gradle 版本的要求。在這種情況下，您必須編輯 gradle/wrapper/gradle-wrapper.properties 檔案中的 Gradle 發布參考資料。以下範例會透過 gradle-wrapper.properties 檔案將 Gradle 版本設為 7.5.1。

...
distributionUrl = https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
...

Android Gradle 外掛程式與 Android Studio 相容性

Android Studio 建構系統以 Gradle 為基礎，Android Gradle 外掛程式則加入了建構 Android 應用程式專用的功能。下表列出各個 Android Studio 版本所需的 Android Gradle 外掛程式版本。

Android Studio 版本	必要的外掛程式版本
Giraffe \| 2022.3.1	3.2-8.1
Flamingo \| 2022.2.1	3.2-8.0
Electric Eel \| 2022.1.1	3.2-7.4
Dolphin \| 2021.3.1	3.2-7.3
Chipmunk \| 2021.2.1	3.2-7.2
Bumblebee \| 2021.1.1	3.2-7.1
Arctic Fox \| 2020.3.1	3.1-7.0

如要瞭解 Android Gradle 外掛程式的新功能，請參閱 Android Gradle 外掛程式版本資訊。

版本編號方式變更 (2020 年 11 月)

我們正在變更 Android Gradle 外掛程式 (AGP) 的版本編號方式，讓版本號碼與基礎 Gradle 建構工具更為一致。

重要變更項目如下：

AGP 現在使用語意化版本編號，主要更新將以破壞性變更為主。
每年都會發布一次 AGP 的主要版本，以便配合 Gradle 的主要版本。
AGP 4.2 之後發布的內容將為 7.0 版本，並必須更新為 Gradle 7.x 版本。每次 AGP 主要版本都必須升級基礎 Gradle 工具的主要版本。
我們會在約一年前提早淘汰 API，並會同時提供替代功能。已淘汰的 API 將在約一年後透過後續重大更新移除。

7.4.0 (2022 年 12 月)

Android Gradle 外掛程式 7.4.0 是主要版本，其中包含多項新功能和改善項目。

相容性

	最低版本	預設版本	附註
Gradle	7.5	7.5	詳情請參閱「更新 Gradle」一節。
SDK 版本工具	30.0.3	30.0.3	安裝或設定 SDK 版本工具。
NDK	不適用	23.1.7779620	安裝或設定 NDK 其他版本。
JDK	11	11	詳情請參閱「設定 JDK 版本」相關說明。

修補程式版本

以下是 Android Gradle 外掛程式 7.4 版的修補程式版本清單。

Android Gradle 外掛程式 7.4.2 版 (2023 年 2 月)

這項次要更新修正了下列錯誤：

已修正問題
問題 #266780231 DexingFileDependenciesTask.outputKeepRules 是目錄，但標示為 OutputFile
問題 #247906487 更新至 7.4 Beta 1 時發生 `AnnotationProcessorOptions.arguments are queried` 錯誤
問題 #266967487 針對測試變化版本使用資訊清單預留位置時，processDebugUnitTestManifest 發生錯誤

Android Gradle 外掛程式 7.4.1 版 (2023 年 2 月)

這項次要更新修正了下列錯誤：

已修正問題
問題 #242831042 從 `destination` 屬性遷移至 `outputLocation` 屬性，避免出現版本已淘汰的警告訊息，為之後的 Gradle 9.0 做好準備
問題 #261329823 AGP 7.4.0-rc01 會破壞 Variant API，並顯示「Querying the mapped value of `map(provider(java.util.Set))` before task '...' has completed is not supported」

AGP 升級小幫手升級後報表與復原功能

AGP 升級小幫手現在提供升級後報表。這份報表會說明已完成的步驟，以及升級是否順利完成。如果升級後在建構或測試專案時遇到問題，這份報表也提供相關操作，可以還原升級小幫手執行的變更。

同時執行專案匯入作業

使用 Gradle 7.4.2 以上版本和 Android Gradle 外掛程式 7.2.0 以上版本時，Studio IDE 現在可同時匯入多個專案。具體來說，當 Android Studio 觸發 Gradle 同步作業時，系統會同時建立資訊來說明版本中包含的專案。這樣通常能加快同步程序，尤其是針對較大型的專案。根據基準測試資料，極大型專案 (有 3,500 個 Gradle 子專案) 建構 Gradle 模型所需的時間可縮減 50%，從 10 分鐘減至 5 分鐘。

Android Gradle 外掛程式指定 JVM 11 位元碼

從 Android Gradle 外掛程式 7.4.0-alpha04 開始，AGP 會內附 JVM 11 位元碼。也就是說，如果您針對 AGP 進行編譯或編寫自訂 Lint 檢查，就必須開始指定 JVM 11 位元碼。其中一個方法是在模組層級的 build.gradle 檔案中加入以下內容：

sourceCompatibility = "11"
targetCompatibility = "11"