Android Gradle 外掛程式 8.3 版本資訊

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

Kotlin

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

Groovy

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

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

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

更新 Gradle

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

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

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

gradle wrapper --gradle-version 8.3

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

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

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

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

Android Studio 版本 所需的 AGP 版本
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

較舊版本

Android Studio 版本 所需的 AGP 版本
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 最低版本
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.4 8.4 詳情請參閱「更新 Gradle」一節。
SDK 版本工具 34.0.0 版 34.0.0 版 安裝設定 SDK 版本工具。
NDK 25.1.8937393 安裝設定 NDK 其他版本。
JDK 17 17 詳情請參閱「設定 JDK 版本」相關說明。

以下是 Android Gradle 外掛程式 8.3 的新功能。

支援 Gradle 版本目錄

Android Studio 支援以 TOML 為基礎的 Gradle 版本目錄,這項功能可讓您集中管理依附元件,並跨模組或專案共用依附元件。Android Studio 現在提供編輯器建議,並與「Project Structure」對話方塊整合,讓您更輕鬆地設定版本目錄。瞭解如何設定及設定 Gradle 版本目錄,或如何將建構遷移至版本目錄

完成程式碼與瀏覽

當您在使用 TOML 檔案格式編輯版本目錄,或是將版本目錄中的依附元件新增至建構檔案時,Android Studio 會提供程式碼完成功能。如要使用程式碼完成功能,請按下 Ctrl+空格鍵 (在 macOS 為 Command + 空格鍵)。此外,您還可以按下 Ctrl+b 鍵 (在 macOS 上為 Command+b 鍵),從應用程式 build.gradle 檔案中的依附元件參考資料快速前往該檔案在版本目錄中宣告的位置。

新增依附元件時完成程式碼

與「Project Structure」對話方塊整合

如果專案使用 TOML 檔案格式所定義的版本目錄,您可以在 Android Studio 中透過「Project Structure」對話方塊的「Variables」檢視畫面 (依序點選「File」>「Project Structure」>「Variables」) 編輯您在該處定義的變數。每個版本目錄都會有一個下拉式選單,列出該目錄中的變數。如要編輯變數,請按一下變數的值並覆寫。儲存這些變更時,TOML 檔案也會隨之更新。

「Project Structure」對話方塊中版本目錄中的變數

您也可以在「Project Structure」對話方塊的「Dependencies」檢視畫面中 (「File」>「Project Structure」>「Dependencies」) 更新依附元件。如要使用「Project Structure」對話方塊更新版本,請前往要編輯的模組和依附元件,然後更新「Requested Version」欄位。儲存這些變更時,TOML 檔案也會隨之更新。請注意,如果是以變數定義依附元件版本,請直接以這種方式更新版本,將變數替換成硬式編碼值。另請注意,無論您是否使用「Project Structure」對話方塊移除依附元件,都不會從版本目錄中移除依附元件。

「Project Structure」對話方塊中版本目錄中的依附元件

已知問題和限制

以下是 Android Studio 對 Gradle 版本目錄支援的已知問題或限制。

  • 在 Kotlin 指令碼檔案中醒目顯示外掛程式別名宣告時發生錯誤:當您新增 alias(libs.plugins.example) 格式的外掛程式宣告時,編輯器會在 libs 部分下方加上紅色底線。這是 Gradle 8.0 以下版本的已知問題,將於日後的 Gradle 版本中解決。

  • Android Studio 僅支援 TOML 格式的版本目錄。目前 Android Studio 程式碼完成、導覽和專案結構對話方塊僅支援以 TOML 檔案格式定義的版本目錄。不過,您仍可直接在 settings.gradle 檔案中新增版本目錄,並在專案中使用其依附元件。

  • 不支援 KTS 建構檔案的導覽功能:目前尚不支援使用 Control 鍵 + 滑鼠 (在 macOS 上按 Command + 點選),前往版本目錄內的依附元件定義。

  • Firebase Assistant 會直接在建構指令碼中新增依附元件:Firebase Assistant 會直接將依附元件直接加入建構指令碼,而非版本目錄。

  • 不支援「查看使用情形」功能:目前不支援尋找其他建構檔案中的版本目錄變數使用情形,無論建構檔案位於 KTS 或 Groovy。也就是說,在版本目錄的變數定義中按下 Control 鍵 (在 macOS 上按 Command + 點選),不會導向使用該變數的建構檔案。

  • 如果 Android Studio 中的「Project Structure」對話方塊位於根 gradle 資料夾中,則會顯示多個目錄檔案,但不會顯示複合式建構的目錄。舉例來說,如果您有兩個目錄檔案,一個用於應用程式,另一個用於複合式建構,則「Project Structure」對話方塊只會顯示應用程式目錄檔案。您可以使用複合式版本,但必須直接編輯其 TOML 檔案。

其他 SDK 深入分析:政策問題

Android Studio 會在 build.gradle.ktsbuild.gradle 檔案中顯示 Lint 警告,而對於在 Google Play SDK 索引中違反 Play 政策的公開 SDK,也會在「Project Structure」對話方塊中顯示 Lint。您應更新違反 Play 政策的所有依附元件,因為這類違規事項可能會導致您日後無法發布至 Google Play 管理中心。違反政策警告會補充 Android Studio 顯示的過時版本警告

Android Studio compileSdk 版本支援

如果專案使用的 compileSdk 不受目前的 Android Studio 版本支援,Android Studio 會顯示警告。如果適用,也會建議改用支援專案使用的 compileSdk 的 Android Studio 版本。請注意,升級 Android Studio 可能也需要升級 AGP。如果目前的 AGP 版本不支援專案使用的 compileSdk,AGP 也會在「Build」工具視窗中顯示警告。

Lint 行為變更

從 Android Gradle 外掛程式 8.3.0-alpha02 開始,在模組上執行 Lint 時,系統會為模組的主要和測試元件執行不同的 Lint 分析工作。之所以會有這種變化,是為了提升效能。 如要還原為先前的行為,請在 gradle.properties 檔案中設定 android.experimental.lint.analysisPerComponent=false