Android Gradle 外掛程式 8.1.0 (2023 年 7 月)

Android Gradle 外掛程式 8.1.0 是主要版本，內含多種新功能及改善項目。

相容性

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

建構設定的預設值為 Kotlin DSL

新專案現在預設使用 Kotlin DSL (build.gradle.kts) 進行建構設定。這比 Groovy DSL (build.gradle) 提供更優異的編輯體驗，因為它支援語法醒目顯示、程式碼完成功能，以及前往宣告的導覽功能。請注意，如果您使用 AGP 8.1 和 Kotlin DSL 進行建構設定，應使用 Gradle 8.1 以獲得最佳體驗。詳情請參閱 Kotlin DSL 遷移指南。

自動支援個別應用程式語言

從 Android Studio Giraffe Canary 7 和 AGP 8.1.0-alpha07 開始，您可以將應用程式設為自動支援個別應用程式語言偏好設定。Android Gradle 外掛程式會根據您的專案資源產生 LocaleConfig 檔案，並在最終資訊清單檔案中加入該檔案的參照，為您省去手動操作的麻煩。AGP 會使用應用程式模組 res 資料夾中的資源和任何程式庫模組依附元件，決定要加入 LocaleConfig 檔案的語言代碼。

請注意，自動個別應用程式語言功能支援在 Android 13 (API 級別 33) 以上版本中執行的應用程式。如要使用這項功能，必須將 compileSdkVersion 設為 33 以上。如要為先前的 Android 版本設定個別應用程式語言偏好，還是需要使用 API 和應用程式內語言選單。

如要啟用自動支援個別應用程式語言功能，請指定預設語言代碼：

  1. 在應用程式模組的 res 資料夾中，建立名為 resources.properties 的新檔案。

  2. 在 resources.properties 檔案中，使用 unqualifiedResLocale 標籤設定預設語言代碼。如要設定語言代碼名稱的格式，請將語言代碼與選用的指令碼和區碼結合，並以連字號分隔。

    舉例來說，假設預設語言代碼是美式英文：

        unqualifiedResLocale=en-US

AGP 會使用 res 資料夾中的 values-* 目錄，將這個預設語言代碼和所有指定替代語言代碼加進自動產生的 LocaleConfig 檔案。

自動支援個別應用程式語言功能預設為關閉。如要開啟這項功能，請在模組層級 build.gradle.kts 檔案 (若使用 Groovy 則為 build.gradle 檔案) 的 androidResources {} 區塊中使用 generateLocaleConfig 設定：

Kotlin

android {
  androidResources {
    generateLocaleConfig = true
  }
}

Groovy

android {
  androidResources {
    generateLocaleConfig true
  }
}

Android Lint 包含指定 JVM 17 的位元碼

從 AGP 8.1.0-alpha04 開始，Android Lint 會包含指定 JVM 17 的位元碼。如果您編寫自訂 Lint 檢查，則必須使用 JDK 17 以上版本進行編譯，並在 Kotlin 編譯器選項中指定 jvmTarget = '17'。

如要進一步瞭解 Lint 工具，請參閱「使用 Lint 檢查項目改善程式碼」。

將原生程式庫壓縮設定移至 DSL

從 AGP 8.1.0-alpha10 開始，如果您未使用 DSL 而非資訊清單設定原生資料庫壓縮功能，系統會顯示警告。以下指南說明如何更新設定以使用 DSL。如需更新相關說明，請使用 AGP 升級小幫手 (依序前往「Tools」>「AGP Upgrade Assistant」)。

如要使用未壓縮的原生程式庫，請從資訊清單中移除 android::extractNativeLibs 屬性，並將以下程式碼加入模組層級 build.gradle.kts 檔案 (若使用 Groovy 則為 build.gradle 檔案)：

Kotlin

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging = false
    }
  }
}

Groovy

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging false
    }
  }
}

實驗性建構旗標

這些是實驗性標記，可用於設定 AGP 8.1 中的版本。

檢舉 新增於 預設值 附註
android.experimental.useDefaultDebugSigningConfigForProfileableBuildtypes AGP 8.0 false 如果在未指定任何簽署設定的情況下啟用此選項，AGP 在執行可剖析或可偵錯的版本時，就會使用預設的偵錯簽署設定。這個旗標預設為停用，目的是鼓勵建構作者宣告特定剖析簽署設定。
android.experimental.library.desugarAndroidTest AGP 8.0 false 這個旗標可讓程式庫建構工具為測試 APK 啟用核心程式庫去除糖化功能，而不會影響產生的 AAR，例如透過 linting。我們預計最終會在 Variant API 中支援這項行為。
android.experimental.testOptions.managedDevices.customDevice AGP 8.0 false 啟用後，Gradle 管理裝置會允許使用者定義的裝置類型，可由外掛程式提供。如要使用 Firebase Test Lab 外掛程式，必須啟用這個標記。
android.lint.printStackTrace AGP 8.0 false 如果啟用，Android Lint 會在當機時列印堆疊追蹤。這個旗標的功能與 LINT_PRINT_STACKTRACE 環境變數相同。
android.experimental.testOptions.managedDevices.maxConcurrentDevices AGP 8.0 無 指定在任何時間點要啟用的 Gradle 管理裝置 (AVD) 並行數量上限。如果值為 0 或負值，則沒有裝置上限。
android.experimental.testOptions.installApkTimeout AGP 8.0 無 安裝 APK 的逾時時間長度 (以秒為單位)。如果值為 0 或負值，則會由 UTP 設為預設值。

已修正問題

Android Gradle 外掛程式 8.1.0 版

已修正問題
Android Gradle 外掛程式
設定快取出現「com.android.build.gradle.task.ShaderCompile」問題
使用 AGP API 在 Java 資源中新增內容會導致設定快取無法使用
[Android Studio : Flamingo | 2022.2.1 Canary 8] liblog.so 封裝在 APK 中
KGP 會在設定期間讀取資訊清單，導致資訊清單變更的相關設定快取失效
合併的資訊清單發生問題時，版本警告訊息不明確
升級至 AGP 7.4 時會導致 StackOverflowError
直接依附 Kotlin 程式庫子專案的動態功能發生 ClassNotFoundException
測試變化版本的資訊清單預留位置導致processDebugUnitTestManifest 失敗
測試變化版本的資訊清單預留位置導致processDebugUnitTestManifest 失敗
命名空間屬性可能屬於 HasAndroidResources
無法停用「Gradle files have changed since last project sync」訊息
沒有較新的 Android Gradle 外掛程式時，系統卻顯示「We recommend using a newer Android Gradle plugin」
測試變化版本的資訊清單預留位置導致processDebugUnitTestManifest 失敗
用於在 CheckAarMetadataTask 中停用編譯 SDK 檢查的布林值旗標
建構錯誤參照 API 級別 34，但該級別不存在
設定 JVM 工具鍊不會影響 JavaCompile 的 targetCompatibility 值
使用萬用字元網域的 Navigation 深層連結項目在合併的資訊清單中沒有「android:host」屬性
自 Android Gradle 外掛程式 8.1 版以來，processDebugMainManifest 任務皆執行失敗
是否可以移除 AnalyticsRecordingTask？
output-metadata.json 內容不一致
是否可以移除 AnalyticsRecordingTask？
output-metadata.json 內容不一致
設定 JVM 工具鍊不會影響 JavaCompile 的 targetCompatibility 值
使用萬用字元網域的 Navigation 深層連結項目在合併的資訊清單中沒有「android:host」屬性
自 Android Gradle 外掛程式 8.1 版以來，processDebugMainManifest 任務皆執行失敗
Android Studio 未遵循 STUDIO_GRADLE_JDK 環境變數
自訂來源類型應建立多個變種版本來源集
DependenciesInfoBuilder 需要更新 API 和相關文件
由於缺少巢狀結構成員，指定 Java 11 的 DexingNoClasspathTransform (minSdk >= 24) 無法執行
DslExtension.Builder.extendProjectWith() 無法以 Groovy 中所述方式運作
新增不使用 kotlin.Pair 的 VariantSelector.withFlavor API
由於「proguard.txt」已變更，AndroidLintAnalysisTask (:lintAnalyzeExternalRelease) 會發生快取失敗的情況
應用程式合併的資訊清單包含來自依附元件的 extractNativeLibs 和 useEmbeddedDex 屬性
AGP：公開 AIDL 工具的路徑和架構 AIDL 檔案做為公用 API
要求：讓 IDE 提供「PermittedSubclasses requires ASM9」的修正項目
錯誤：「Enable KSP and use the KSP processor for this dependency instead」只出現在單一網站上
Gradle 8.1 因 .gradle/.android/analytics.settings 造成設定快取中斷
agp 8.1.0 中的 generateLocaleConfig 採用非確定性排序，會造成可重現的建構作業中斷
Dexer (D8)
近期更新後，核心程式庫會對異常終止的應用程式進行脫糖處理。
API 21 發生 agp 8.1.0 迴歸問題 - F/dex2oat ( 4176)：art/compiler/driver/compiler_driver.cc:1181] 檢查失敗：!method->IsAbstract()
Lint
Lint 只會檢查直接實作的介面是否實施安全轉型，不會檢查繼承的介面
Lint 未檢查呼叫接受器是否有效轉換
TypedArray#close (API 31) 未完成脫糖程序，但在用於 try-with-resources 時，AS 並未顯示警告
錯誤：系統顯示「The 'BC' provider is deprecated and as of Android P...」的誤判警示
Kotlin 升級至 1.8.0 後，Lint 出現記憶誤判狀況
在含有列舉參數的方法中執行 SDK_INT 檢查時，出現錯誤的 Lint 警告
Typographyquotes Lint 檢查對逸出引號沒有作用
TrustAllX509TrustManager Lint 檢查未正確標記擴充 X509TrustManager 的介面
僅針對已取代的修正項目重新格式化插入的程式碼
Lint：意圖預覽功能針對 ReplaceStringQuickFix 擲回例外狀況
縮減器 (R8)
VerifyError：搭配 Kotlin 1.8.20 使用 R8 時，類別遭驗證器拒絕
AGP 8 上的 R8 會中斷 Google Fit 服務
來源檔案資訊中剩餘的名稱如與輸入名稱重疊，加入這些資訊後將無法正確顯示
R8 在 Compose 構建期間失敗並顯示 ArrayIndexOutOfBoundsException
簡易 StringBuilder 相關程式碼缺少要在發布或 debuggable=false 模式下附加的結尾呼叫
VirtualDispatchMethodArgumentPropagator.shouldActivateMethodStateGuardedByBounds() 方法出現邊角案例
dex-startup-optimization 導致 java.lang.VerifyError：拒絕類別
在 Android 12 以上版本發生當機並顯示驗證錯誤

Android Gradle 外掛程式 8.1.1 版

已修正問題
Dexer (D8)
Java 16 記錄：equals(null) 會擲回 NullPointerException
縮減器 (R8)
java.lang.VerifyError：類別遭驗證器拒絕
使用 Apache POI 程式庫時，建構作業會在執行 :minifyReleaseWithR8 時卡住
在啟用 r8 最佳化功能時拒絕叫用
java.lang.reflect.Executable 的 NoClassDefFoundError

Android Gradle 外掛程式 8.1.2 版

已修正問題
Android Gradle 外掛程式
Android 程式庫模組不提供 androidResources
[AGP 8.1.0] 如果 splits.abi.isEnable 和 testOptions.unitTests.isIncludeAndroidResources 皆為 true，./gradlew 測試會失敗，並顯示「Unable to find manifest output」
縮減器 (R8)
如果移除空值檢查，Kotlin 1.9 會導致 Kotlin lambda 遭到 R8 刪除
R8 執行失敗，並顯示 play-services-measurement-21.3.0-runtime.jar 的「Undefined value encountered during compilation」錯誤訊息

Android Gradle 外掛程式 8.1.3 版

已修正問題
Android Gradle 外掛程式
[AGP 8.1.0] 如果 splits.abi.isEnable 和 testOptions.unitTests.isIncludeAndroidResources 皆為 true，./gradlew 測試會失敗，並顯示「Unable to find manifest output」
更新至 AGP 8.1 後建構作業失敗

Android Gradle 外掛程式 8.1.4 版

已修正問題
Android Gradle 外掛程式
如果子專案類別已透過構件轉換作業完成 dex 處理，請不要在子專案類別上執行 dex 工作