Android Gradle 外掛程式 8.9 版本資訊

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

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.9.0 版:

KotlinGroovy
plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}
plugins {
    id 'com.android.application' version '8.9.0' apply false
    id 'com.android.library' version '8.9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.10' apply false
}

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

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

更新 Gradle

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

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

外掛程式版本Gradle 最低版本需求
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
7.47.5
外掛程式版本所需 Gradle 版本
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 版本設定為 8.9。請注意,您必須執行這個指令「兩次」,才能升級 Gradle 和 Gradle 包裝函式 (詳情請參閱「升級 Gradle 包裝函式」一文)。

gradle wrapper --gradle-version 8.9

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

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

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

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

Android Studio 版本 所需的 AGP 版本
Meerkat | 2024.3.1 3.2-8.9
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
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 版本低於專案的 targetSdkcompileSdk 所需版本,可能會導致非預期的問題。建議您使用最新的 Android Studio 和 AGP 預先發布版,處理針對 Android 作業系統預先發布版的專案。您可以一併安裝 Android Studio 的預先發布版和穩定版

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

API 級別 Android Studio 最低版本 AGP 最低版本
蜜糖果仁千層酥預覽 Meerkat | 2024.3.1 8.9.0
35 Koala 功能推送 | 2024.2.1 8.6.0
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.9 支援的最高 API 級別為 API 級別 35。以下提供其他相容性資訊:

最低版本 預設版本 附註
Gradle 8.11.1 8.11.1 詳情請參閱「更新 Gradle」一節。
SDK 版本工具 35.0.0 35.0.0 安裝設定 SDK 版本工具。
NDK 27.0.12077973 安裝設定 NDK 其他版本。
JDK 17 17 詳情請參閱「設定 JDK 版本」相關說明。

已修正問題

Android Gradle 外掛程式 8.9.0 版

已修正問題
Android Gradle 外掛程式
當 GMD 設定工作因磁碟空間不足而失敗時,提供可採取行動的錯誤訊息
com.android.settings 外掛程式無法辨識 targetSdk
無用的錯誤:「未指定 compileSdkVersion」請將其新增至 build.gradle」
「Build」選單中缺少「Clean build」
或許可以讓 AGP 內建的 Kotlin 支援功能自動新增 Kotlin stdlib 依附元件
更新 shouldConfigureKotlinPlatformAttribute,以便處理內建的 Kotlin 支援
針對 `checkTestedAppObfuscationRelease` 在錯誤訊息中提供 Kotlin Gradle 語法
未解決的依附元件時,可改善 Fused Library 錯誤
系統屬性不會從 gradle.properties 傳送至 R8 Gradle 工作者,而是在個別程序中傳送
將 BuiltArtifact.outputFile 設為檔案類型
未在融合式程式庫上提供命名空間,不會顯示正確的錯誤訊息
AGP 7.1.0-alpha08 中的 Lint 選項不允許使用 stdout
Android Gradle 外掛程式:變化版本應公開來源集合名稱
設定快取對 TERM 環境變數的設定十分脆弱
啟用統計資料時,AndroidComponentsExtension.addSourceSetConfigurations 會損毀
初始化指令碼 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle' 行:162
啟用統計資料時,AndroidComponentsExtension.addSourceSetConfigurations 會損毀
Dexer (D8)
java.lang.VerifyError:類別遭驗證器拒絕:[0x430] copy1 v2<-v264 type=Undefined cat=3
Lint
Lint 在 Lint Gradle 檢查時異常終止
Lint 失敗,並顯示 InstantiationException,但 Lint 堆疊追蹤中沒有例外狀況訊息
Lint 檢查出現偽陽性,android.permission.SCHEDULE_EXACT_ALARM 權限僅授予系統應用程式
應將 StringFormatInvalid 檢查套用至 Compose 字串資源方法
RequiresFeature 註解無法用於 Kotlin 檔案
kotlin android.os.Handler removeCallbacks Runnable
使用 shift 時,定義上的 WrongConstant lint 會顯示錯誤,而非常數的用法
出現兩次 WrongConstant Lint
在 API 26 以下版本中,使用不支援的 Java nio API 時發生執行階段例外狀況 (沒有 Lint 錯誤)
Lint 會禁止使用 RequiresApi,即使是在測試中的私人輔助程式方法也是如此
在 Android Studio 中使用 .hasRoute(Route::class) 時,K2 模式會擲回 RestrictedApi 警告
Lint 建議您將測試中的 @RequiresExtension 替換為 @SdkSuppress,後者不支援 SDK 擴充功能
當 FrameLayout 與 fitSystemWindows 搭配使用,用於包裝需要自訂邊框的子項 RelativeLayout 時,Lint 會錯誤地回報不必要的巢狀版面配置。
CoarseFineLocation Lint 規則未考量 maxSdkVersion 屬性
在 Lint 8.7.3 中,AppLinkSplitToWebAndCustom 是 UnknownIssue
Lint 檢查 StringEscapeDetector 在「\\ "」上異常終止
密封介面中的「@Parcelize」註解出現錯誤的 Lint 警告
編輯 Kotlin 文字時,AS 2024.3.1.4 會間歇性當機。
Lint 整合
建構應用程式套件時,lintVitalRelease 不會自動執行
縮減器 (R8)
升級至 AGP 8.8 後,Gson ProGuard 無法正常運作
java.lang.VerifyError:類別遭驗證器拒絕
使用 AGP 8.10.0-alpha04 中所附的 R8 進行壓縮時,Leanback 會當機