關於 Android Gradle 外掛程式

Android Studio 建構系統以 Gradle 為基礎，Android Gradle 外掛程式則加入了建構 Android 應用程式專用的功能。

本頁面說明如何讓 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.kts 檔案內操作。這個外掛程式版本會套用到該 Android Studio 專案內建構的所有模組。以下範例會透過 build.gradle.kts 檔案將外掛程式設為 9.0 版：

Kotlin

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

Groovy

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

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

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

更新 Gradle

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

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

外掛程式版本Gradle 最低版本需求
9.09.1.0
8.138.13
8.128.13
8.118.13
8.108.11.1
8.98.11.1
8.88.10.2
8.78.9
8.68.7
8.58.7
8.48.6
8.38.4
8.28.2
8.18.0
8.08.0

較舊版本

外掛程式版本所需 Gradle 版本
7.47.5
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0+6.7.1
4.1.0+6.5+
4.0.0+6.1.1+
3.6.0 - 3.6.45.6.4+
3.5.0 - 3.5.45.4.1+
3.4.0 - 3.4.35.1.1+
3.3.0 - 3.3.34.10.1+
3.2.0 - 3.2.14.6+
3.1.0+4.4+
3.0.0+4.1+
2.3.0+3.3+
2.1.3 - 2.2.32.14.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.2.1 - 2.3

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

gradle wrapper --gradle-version 9.1.0

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

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

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

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

Android Studio 版本 所需的 AGP 版本
Otter 3 功能推送 | 2025 年 2 月 3 日 4.0-9.0
Otter 2 功能推送 | 2025 年 2 月 2 日 4.0-8.13
Otter | 2025.2.1 4.0-8.13
Narwhal 4 功能推送 | 2025 年 1 月 4 日 4.0-8.13
Narwhal 3 功能推送 | 2025 年 1 月 3 日 4.0-8.13
Narwhal 功能推送 | 2025.1.2 4.0-8.12
Narwhal | 2025.1.1 3.2-8.11
Meerkat 功能推送 | 2024 年 3 月 2 日 3.2-8.10
Meerkat | 2024.3.1 3.2-8.9

較舊版本

Android Studio 版本 所需的 AGP 版本
Ladybug 功能推送 | 2024 年 2 月 2 日 3.2-8.8
Ladybug | 2024.2.1 3.2-8.7
Koala 功能推送 | 2024.1.2 3.2-8.6
Koala | 2024.1.1 3.2-8.5
Jellyfish | 2023.3.1 3.2-8.4
Iguana | 2023.2.1 3.2-8.3
Hedgehog | 2023.1.1 3.2-8.2
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 外掛程式版本資訊。

支援 Android API 級別的最低工具版本

Android Studio 和 AGP 有支援特定 API 級別的最低版本。如果您使用的 Android Studio 或 AGP 版本低於專案的 targetSdk 或 compileSdk 所需版本，可能會導致非預期的問題。建議您使用最新的 Android Studio 和 AGP 預先發布版，處理針對 Android 作業系統預先發布版的專案。您可以一併安裝 Android Studio 的預先發布版和穩定版。

Android Studio 和 AGP 的最低版本如下：

API 級別 Android Studio 最低版本 AGP 最低版本
36.1 Narwhal 3 功能推送 | 2025 年 1 月 3 日 8.13.0
36.0 Meerkat | 2024.3.1 Patch 1 8.9.1
35 Koala 功能推送 | 2024.2.1 8.6.0
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2