Android Studio 建構系統以 Gradle 為基礎，Android Gradle 外掛程式則加入了建構 Android 應用程式專用的功能。雖然 Android Gradle 外掛程式 (AGP) 通常會與 Android Studio 一併更新，但外掛程式 (還有 Gradle 系統的其他內容) 可以與 Android Studio 分開執行，並可單獨更新。
本頁面將說明如何讓 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 檔案將外掛程式設定為 8.4.0 版：
Kotlin
plugins {
id("com.android.application") version "8.4.0" apply false
id("com.android.library") version "8.4.0" apply false
id("org.jetbrains.kotlin.android") version "1.9.23" apply false
}
Groovy
plugins {
id 'com.android.application' version '8.4.0' apply false
id 'com.android.library' version '8.4.0' apply false
id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
}
注意：請勿在版本號碼中使用動態依附元件，例如 'com.android.tools.build:gradle:8.4.+'。使用這項功能可能會導致非預期的版本更新情形，並難以解析版本差異。
如果您尚未下載指定的外掛程式版本，當您下次建構專案，或在 Android Studio 選單列中依序點選「File」>「Sync Project with Gradle Files」時，Gradle 就會下載該版本。
更新 Gradle
更新 Android Studio 時，系統可能會要求同時將 Gradle 更新 為可供使用的最新版本。您可以選擇接受更新，也可根據專案的版本需求手動指定版本。
下表列出各個 Android Gradle 外掛程式版本所需的 Gradle 版本。為獲得最佳效能，請務必使用最新版本的 Gradle 及外掛程式。
| 外掛程式版本 | Gradle 最低版本需求 |
|---|---|
| 8.4 | 8.6 分 |
| 8.3 | 8.4 |
| 8.2 | 8.2 |
| 8.1 | 8.0 |
| 8.0 | 8.0 |
| 7.4 | 7.5 |
較舊版本
| 外掛程式版本 | 所需 Gradle 版本 |
|---|---|
| 7.3 | 7.4 |
| 7.2 | 7.3.3 |
| 7.1 | 7.2 |
| 7.0 | 7.0 |
| 4.2.0+ | 6.7.1 |
| 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 版本設定為 8.4。請注意，您必須執行這個指令「兩次」，才能升級 Gradle 和 Gradle 包裝函式 (詳情請參閱「升級 Gradle 包裝函式」一文)。
gradle wrapper --gradle-version 8.4
不過，這個方法在某些情況下可能會失敗，例如您剛更新了 AGP，而更新後的版本不再符合目前 Gradle 版本的要求。在這種情況下，您必須編輯 gradle/wrapper/gradle-wrapper.properties 檔案中的 Gradle 發布參考資料。以下範例會透過 gradle-wrapper.properties 檔案將 Gradle 版本設定為 8.4。
...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.4-bin.zip
...
Android Gradle 外掛程式與 Android Studio 相容性
Android Studio 建構系統以 Gradle 為基礎，Android Gradle 外掛程式 (AGP) 則加入了建構 Android 應用程式專用的功能。下表列出各個 Android Studio 版本所需的 AGP 版本。
| Android Studio 版本 | 所需的 AGP 版本 |
|---|---|
| 《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 |
較舊版本
| Android Studio 版本 | 所需的 AGP 版本 |
|---|---|
| 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 最低版本 |
|---|---|---|
| VanillaIceCream 預覽畫面 | Jellyfish | 2023.3.1 | 8.4 |
| 34 | Hedgehog | 2023.1.1 | 8.1.1 |
| 33 | Flamingo | 2022.2.1 | 7.2 |
版本編號方式變更 (2020 年 11 月)
我們正在變更 Android Gradle 外掛程式 (AGP) 的版本編號方式，讓版本號碼與基礎 Gradle 建構工具更為一致。
重要變更項目如下：
AGP 現在使用語意化版本編號， 主要更新將以破壞性變更為主。
每年都會發布一次 AGP 的主要版本， 以便配合 Gradle 的主要版本。
AGP 4.2 之後發布的內容將為 7.0 版本， 並必須更新為 Gradle 7.x 版本。每次 AGP 主要版本都必須升級 基礎 Gradle 工具的主要版本。
我們會在約一年前提早淘汰 API， 並會同時提供替代功能。已淘汰的 API 將在約一年後透過後續重大更新移除。
相容性
Android Gradle 外掛程式 8.3 支援的最高 API 級別為 API 級別 34。其他相容性資訊如下：
| 最低版本 | 預設版本 | 附註 | |
|---|---|---|---|
| Gradle | 8.6 分 | 8.6 分 | 詳情請參閱「更新 Gradle」一節。 |
| SDK 版本工具 | 34.0.0 版 | 34.0.0 版 | 安裝或設定 SDK 版本工具。 |
| NDK | 不適用 | 26.1.10909125 | 安裝或設定 NDK 其他版本。 |
| JDK | 17 | 17 | 詳情請參閱「設定 JDK 版本」相關說明。 |
以下是 Android Gradle 外掛程式 8.4 的新功能。
修補程式版本
以下是 Android Studio Jellyfish 和 Android Gradle 外掛程式 8.4 的修補程式版本清單。
Android Studio Jellyfish | 2023.3.1 修補程式 2 和 AGP 8.4.2 (2024 年 6 月)
重要安全性更新：Android Studio Iguana | 2023.2.1 以上版本提供的 GitHub 外掛程式中的安全漏洞，可能會向未經授權的對象暴露存取權杖。
修正方法：Jetbrains 已解決 IntelliJ 平台產品中的問題，現已在 Android Studio Jellyfish | 2023.3.1 修補程式 2 (2023.3.1.20) 提供修正內容。
如果您已使用穩定版建立 Android Studio 版本，只要依序點選「Help」>「Check for Updates」 (在 macOS 上則為「Android Studio」>「Check for Updates」) 即可取得更新。否則，請下載最新的穩定版本。
此外，如果您經常在 IDE 中使用 GitHub 提取要求功能，強烈建議您撤銷外掛程式正在使用的所有 GitHub 權杖。由於這個外掛程式可以使用 OAuth 整合或個人存取權杖 (PAT)，請同時檢查兩者，並視需要撤銷：
- 如要撤銷 OAuth 整合功能的存取權，請前往應用程式 > 授權 OAuth 應用程式並撤銷 JetBrains IDE Integration 權杖的存取權。
- 如要撤銷 PAT 的存取權，請前往個人存取權杖，然後刪除為 GitHub 外掛程式核發的權杖。預設權杖名稱為 IntelliJ IDEA GitHub 整合外掛程式，但您可能使用的是自訂名稱。
撤銷權杖的存取權後，您必須再次設定外掛程式，讓所有外掛程式功能(包括 Git 作業) 恢復運作。
對於造成您的不便，我們深感抱歉。請強制所有使用者立即更新，以保護他們的程式碼和資料。
另外，這個次要更新版本修正了這裡所列的錯誤。
Android Studio Jellyfish | 2023.3.1 修補程式 1 和 AGP 8.4.1 (2024 年 5 月)
這個次要更新版本修正了這裡所列的錯誤。
程式庫類別遭到縮減
從 Android Gradle 外掛程式 8.4 版開始，如果 Android 程式庫專案已縮減，將會發布縮減程式類別以在專案間發布。換句話說，如果應用程式依附於 Android 程式庫子專案的縮減版本，APK 就會包含縮減後的 Android 程式庫類別。如果 APK 中缺少類別，您可能需要調整程式庫保留規則。
如果您正在建構並發布 AAR，AAR 會包含程式庫仰賴的本機 Jar 進行取消縮減，因此程式碼縮減器不會在這些元件上執行。
如要還原為先前的行為，請在 gradle.properties 檔案中設定 android.disableMinifyLocalDependenciesForLibraries 並回報錯誤。日後的 AGP 版本將會移除此標記。