Android Gradle 外掛程式 8.0.0 版 (2023 年 4 月)

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

相容性

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

修補程式版本

以下是 Android Gradle 外掛程式 8.0 版的修補程式版本清單。

Android Gradle 外掛程式 8.0.2 版 (2023 年 5 月)

如需 AGP 8.0.2 修正的錯誤清單,請參閱 Android Studio 2022.2.1 已解決的問題

Android Gradle 外掛程式 8.0.1 版 (2023 年 5 月)

這項次要更新修正了下列錯誤:

已修正問題
從 AGP 7.2.2 升級到 7.4.0 後,出現「No VersionRequirement with the given id in the table」錯誤
markTypeAsLive AGP 7.4.1 發生 R8 NullPointerException
[R8 4.0.53] Android 11 發生類別驗證失敗的嚴重問題

重大變更:模組層級建構指令碼中需要命名空間

您必須在模組層級的 build.gradle.kts 檔案中設定命名空間,而非在資訊清單檔案中設定。您可以從 AGP 7.3 開始使用 namespace DSL 屬性。詳情請參閱「設定命名空間」。

遷移至命名空間 DSL 時,請注意下列問題:

  • 在某些情況下,舊版 AGP 會從主要命名空間或應用程式 ID 推斷出錯誤的測試命名空間。如果 AGP 升級工具發現專案的主要命名空間和測試命名空間相同,就會封鎖升級作業。如果升級遭到封鎖,您必須手動變更 testNamespace,並據此修改原始碼。
  • 變更測試命名空間後,程式碼可能會編譯,但檢測測試在執行階段失敗。如果檢測設備測試原始碼參照了在 androidTest 和應用程式來源中定義的資源,就會發生這種情況。

詳情請參閱問題 #191813691 的註解 #19

重大變更:建構選項的預設值

從 AGP 8.0 開始,這些旗標的預設值已變更,以改善建構效能。如需調整程式碼以支援部分變更的相關說明,請使用 AGP 升級小幫手 (依序前往「Tools」>「AGP Upgrade Assistant」)。升級工具可引導您更新程式碼,以便配合新行為,或設定標記以保留先前的行為。

檢舉 新的預設值 先前的預設值 附註
android.defaults.buildfeatures.buildconfig false true 根據預設,AGP 8.0 不會產生 BuildConfig。您需要在需要的專案中使用 DSL 指定這個選項。
android.defaults.buildfeatures.aidl false true AGP 8.0 預設不會啟用 AIDL 支援。您需要在需要的專案中使用 DSL 指定這個選項。這個標記預計會在 AGP 9.0 中移除。
android.defaults.buildfeatures.renderscript false true AGP 8.0 預設不會啟用 RenderScript 支援功能。您需要在需要的專案中使用 DSL 指定這個選項。這個標記預計會在 AGP 9.0 中移除。
android.nonFinalResIds true false AGP 8.0 預設會產生含有非最終欄位的 R 類別。
android.nonTransitiveRClass true false AGP 8.0 只會針對目前模組中定義的資源產生 R 類別。
android.enableR8.fullMode true false AGP 8.0 預設會啟用 R8 完整模式。詳情請參閱R8 全模式

破壞性變更:強制執行建構選項值

從 AGP 8.0 開始,您將無法再變更這些旗標的值。如果您在 gradle.properties 檔案中指定這些值,系統會忽略該值,並由 AGP 列印警告。

檢舉 強制值 附註
android.dependencyResolutionAtConfigurationTime.warn true 如果 AGP 8.0 在設定階段偵測到設定解析,就會發出警告,因為這會對 Gradle 設定時間造成負面影響。
android.r8.failOnMissingClasses true 如果缺少可確保更佳 DEX 最佳化的類別,AGP 8.0 就會導致使用 R8 的建構作業失敗。如要解決這個問題,您需要新增缺少的程式庫或 -dontwarn 保留規則。詳情請參閱「R8 縮減器缺少類別警告」。
android.testConfig.useRelativePath true 啟用單元測試中使用 Android 資源、資產和資訊清單的支援功能後,AGP 8.0 會產生僅包含相對路徑的 test_config.properties 檔案。這可確保 Android 單元測試一律使用 Gradle 建構快取。
android.useNewJarCreator true AGP 在建立 JAR 檔案時會使用 Zipflinger 程式庫,以改善建構效能。
android.bundletool.includeRepositoriesInDependencyReport true 啟用在 AAB 和 APK 中新增 SDK 依附元件資訊的功能後,AGP 8.0 也會在這些資訊中新增專案存放區清單。詳情請參閱「Play 管理中心的依附元件資訊」。
android.enableArtProfiles true 系統現在會一律產生基準設定檔。詳情請參閱「基準設定檔」。
android.enableNewResourceShrinker true 根據預設,使用新的資源 shinker 實作項目。新的資源縮減器支援動態功能。
android.enableSourceSetPathsMap true 用於計算相對資源路徑對應項目,以便 Gradle 建構作業更頻繁地更新。
android.cacheCompileLibResources true 根據預設,編譯的程式庫資源現在可以快取,因為 Gradle 會追蹤相對於專案位置的資源檔案。必須啟用 android.enableSourceSetPathsMap
android.disableAutomaticComponentCreation true AGP 8.0 預設不會建立 SoftwareComponent。相反地,AGP 只會為使用發布 DSL 設定要發布的變化版本建立 SoftwareComponent。

執行設定檔的新穩定旗標

AGP 包含新的旗標 android.settings.executionProfile。使用這個標記,即可覆寫 SettingsExtension 中的預設執行設定檔。詳情請參閱設定外掛程式說明文件

如要預覽實驗性標記,請參閱預覽版本資訊

不支援 Kotlin 延遲屬性指派

如果您使用 Gradle 的 Kotlin DSL 建構指令碼,請注意,Android Studio 和 AGP 8.0 不支援使用 = 運算子的實驗性屬性指派。如要進一步瞭解這項功能,請參閱版本資訊說明文件

版本分析器工作類別

自 Android Studio Flamingo 起,Build Analyzer 針對影響建構時間的任務提供新的預設檢視畫面。如果專案使用 AGP 8.0 以上版本,版本分析器會依類別將工作群組化,而非個別顯示。舉例來說,Android 資源、Kotlin 或 Dexing 專屬的工作會分組,然後依建構時間長度排序。這樣一來,您就能輕鬆瞭解哪個類別對建構時間的影響最大。展開每個類別後,系統會顯示對應的工作清單。如要個別顯示工作,而不進行分組,請使用「Group by」下拉式選單。

版本分析器工作類別。

新設定外掛程式

AGP 8.0.0-alpha09 推出了新的設定外掛程式。設定外掛程式可讓您將全域設定 (適用於所有模組的設定) 集中在同一個位置,這樣就不必在多個模組中複製及貼上設定。此外,您可以使用設定外掛程式建立工具執行設定檔,或不同的執行工具指示,並在其中切換。

如要使用設定外掛程式,請在 settings.gradle 檔案中套用外掛程式:

apply plugin 'com.android.settings'

集中管理全域設定

如要設定全域設定,請在 settings.gradle 檔案中使用新的 android 區塊。範例如下:

android {
  compileSdk 31
  minSdk 28
  ...
}

工具執行設定檔

設定外掛程式也能讓您為部分工具建立執行設定檔。執行設定檔會決定工具的執行方式;您可以根據環境選取不同的執行設定檔。在執行設定檔中,您可以為工具設定 JVM 引數,並將其設為在個別程序中執行。目前僅支援 R8 工具

建立執行設定檔,並在 settings.gradle 檔案中設定預設執行設定檔,如以下範例所示:

android {
  execution {
    profiles {
      high {
        r8 {
          jvmOptions += ["-Xms2048m", "-Xmx8192m", "-XX:+HeapDumpOnOutOfMemoryError"]
          runInSeparateProcess true
        }
      }
      low {
        r8 {
          jvmOptions += ["-Xms256m", "-Xmx2048m", "-XX:+HeapDumpOnOutOfMemoryError"]
          runInSeparateProcess true
        }
      }
      ci {
        r8.runInSeparateProcess false
      }
    }
    defaultProfile "low"
  }
}

如要覆寫預設設定檔,請使用 gradle.properties 檔案中的 android.experimental.settings.executionProfile 屬性選取其他設定檔:

android.experimental.settings.executionProfile=high

您也可以使用指令列設定這項屬性,以便設定不同的工作流程。舉例來說,如果您有持續整合工作流程,可以使用指令列變更執行設定檔,而無須變更 settings.gradle 檔案:

./gradlew assembleRelease \
  -Pandroid.experimental.settings.executionProfile=ci

若要執行 AGP 8.0,須使用 JDK 17

現在如果要用 Android Gradle 外掛程式 8.0 建構應用程式,則必須使用 JDK 17 才能執行 Gradle。Android Studio Flamingo 內已封裝 JDK 17,並設定讓 Gradle 預設使用,因此,大部分的 Android Studio 使用者都不必變更專案設定。

如果您需要手動設定 AGP 在 Android Studio 使用的 JDK 版本,則需要使用 JDK 17 以上版本。

使用獨立於 Android Studio 之外的 AGP 時,請將 JAVA_HOME 環境變數-Dorg.gradle.java.home 指令列選項設為 JDK 17 安裝目錄,藉此升級 JDK 版本。

已修正問題

Android Gradle 外掛程式 8.0.0 版

已修正問題
Android Gradle 外掛程式
MergeResources 工作中有不穩定的建構失敗
JavaPluginConvention 和 HasConvention 已淘汰
新轉換 API 的檔案位置錯誤且不一致
Android Gradle 外掛程式不應使用已淘汰的 GUtil.toWords(string) 函式
Android Gradle 外掛程式不應使用已淘汰的 ConfigurationUtil.configure(closure, target) 函式
更新 AGP 測試以使用 KGP 1.7.20-Beta 版
Gradle 7.4 失敗 (無法建立 AnalyticsService 的執行個體)
AGP 7.4.0-alpha09 上的 javac 推出新的「不明列舉常數」
即使啟用設定快取,MergeGeneratedProguardFilesCreationAction 設定速度仍然變慢
[AGP] 將產生的來源目錄新增至 IDE 模型 (Variant API)
JavaPluginConvention 和 HasConvention 已淘汰
R8 在預設狀態下不應加入 ignorewarnings
ProGuard 檔案不存在時收到警告
AGP 7.3.0 中斷 Gradle 平台專案的 Gradle 同步處理
apksig 程式庫:ApkVerifier$Result.getV4SchemeSigners() 標示為私人
如未啟用涵蓋範圍,則不應建立 androidJacocoAnt 設定
在程式庫元件中使用 @IntDef 不會在 aar 中產生 annotation.zip
找不到 的常見超級類型
新增 LINT_PRINT_STACKTRACE=true 的 Gradle 屬性版本
過時的 Prefab 構件被封裝到 AAR 中
改用 outputLocation 屬性來替換 destination 屬性,避免出現方法淘汰的警告訊息,為之後的 Gradle 9.0 做好準備
設定 JavaCompile 工作時將「--release」旗標納入考量
[AGP-7.3.0-beta03] XML 宣告後有空白行時,ShrinkResourcesNewShrinkerTask 失敗
根據預設,LintVital 目標會在偵錯變化版本中執行
ProGuard 檔案不存在時收到警告
AGP 嘗試在工作執行階段新增 kotlinOptions.freeCompilerArgs
Gradle 同步處理失敗:同步失敗:原因不明
DependencyReportTask 與設定快取不相容
在 build.gradle 中透過 resValue 覆寫資源會導致出現「Error: Duplicate resources」訊息
「偵錯」建構類型有預設的簽署金鑰,但其他類型沒有
使用動態功能和資源縮減會造成執行階段異常終止
「偵錯」建構類型有預設的簽署金鑰,但其他類型沒有
在 Lint 模型的主要來源供應器中,系統將產生的來源目錄列為 Java 目錄
Gradle 8.0-milestone-2 會導致 AGP 出現例外狀況
針對應用程式和程式庫最佳化資訊清單合併
將 gradle-settings-api 新增至 javadoc 產生項目
AGP 7.4.0-alpha09 上的 javac 推出新的「不明列舉常數」
AGP 7.4.0-alpha09 會產生不會上傳至 Firebase 應用程式發布的建構作業
Lint 工作的最新狀態檢查未納入模組中的 lint.xml
Android Gradle 外掛程式 7.0 以上版本和 Android 測試問題:找不到資源:ID
configureCMakeDebug 因空值指標例外狀況而異常終止
IllegalAccessError 將專案升級到 AS2022.2.1.5,FireBasePerfPlugin
同步處理失敗,發生以下隱密錯誤:「Collection contains no element matching the predicate」(集合不包含與述詞相符的元素)。
檢測 API 不會轉換本機檔案依附元件
更新至 7.4 Beta 1 時發生「AnnotationProcessorOptions.arguments are queried」錯誤
將 Gradle 公開外掛程式移至 gradle-api 並移除 BasePlugin.getExtension
未使用 r8.jvmArgs
要求 AGP 版本至少為 JDK17
AGP 8.0.0 A8 會破壞基準設定檔
在 AGP 8.0 的 CheckAarMetadataTask 訊息中,將「compileSdkVersion」變更為「compileSdk」
AGP 7.4.0-rc01 會破壞 Variant API,並顯示「Querying the mapped value of map(provider(java.util.Set)) before task '...' has completed is not supported」
設定快取出現「com.android.build.gradle.task.ShaderCompile」問題
使用 AGP API 在 Java 資源中新增內容會導致設定快取無法使用
Lint 外掛程式並非 gradle-api 的一部分
DexingFileDependenciesTask.outputKeepRules 是一個目錄,但標示為 OutputFile
升級至 AGP 7.4 時會導致 StackOverflowError
測試變化版本的資訊清單預留位置導致processDebugUnitTestManifest 失敗
Lint 在沒有依附元件的情況下存取來源集資訊
建構錯誤參照 API 級別 34,但該級別不存在
沒有較新的 Android Gradle 外掛程式時,系統卻顯示「We recommend using a newer Android Gradle plugin」
android.injected.testOnly=false 無法運作
Dexer (D8)
將 AS Canary 6 升級至 7 後,發生與全域合成項目相關的 Dex 合併錯誤
將 Kotlin 中繼資料程式庫更新至 0.6.0 版
API 級別 28 至 30 似乎需要針對 JDK-8272564 的解決方法
Lint
ResourceType Lint 檢查功能無法檢查 Kotlin 來源的錯誤
VersionChecks 不會處理 Kotlin 範圍檢查
換行時 InlinedApi 會出現誤判
關於 openInputStream 的 Lint Recycle 偽陽性情況
[BuildTool/Lint] ChecksSdkIntAtLeast 建構函式屬性
Lint:部分結果合併失敗
Android Studio 會誤將指定版本標示為過時。
AndroidDeprecationInspection.DeprecationFilter EP 從未在 android-plugin.xml 檔案中註冊
AccessibilityDetector Lint 檢查說明過舊
Lint SDK_INT 檢查應瞭解暫時性的本機變數
TestMode.TYPE_ALIAS 將函式類型取代為 typealias 時發生錯誤
錯誤:在目前的程式碼區塊之外建立 ObjectAnimator 時,出現表示無法啟動的錯誤警告 #38
Lint:在 mergeOnly 模式下查詢應用程式執行個體卻產生 NPE
NonConstantResourceId Lint 規則無法順利偵測,因此無法從資源 ID 指派常數值
未顯示有關檢視畫面 ID 的錯誤
無法將 Lint 資源快取結果還原序列化,導致產生 Lint 錯誤 (但應為警告)
AGP Flamingo Alpha 8 Lint NewApi 脫糖迴歸
TypedArray#close (API 31) 沒有執行脫糖程序,但是在嘗試使用資源時,AS 不會顯示警告
Lint 未檢查呼叫接受器是否有效轉換層級
Lint 只會檢查直接實作的介面是否安全轉換層級,不會檢查繼承的介面
Lint 整合
基準檔案目前為 Lint 工作的輸入和輸出內容
縮減器 (R8)
CF 影格驗證器中的 NPE/斷言錯誤
移除欄位查詢快取之後發生迴歸問題
「:app:minifyVariantWithR8」在 AGP 7.4.0-beta02 中擲回 NullPointerException
-allowaccessmodification 時顯示 R8: ClassNotFoundException
在中繼資料新增對結構定義接收器的支援
java.lang.VerifyError:「Verifier rejected class androidx.compose.ui.graphics.colorspace.o: void androidx.compose.ui.graphics.colorspace.o.(java.lang.Object) failed to verify: void androidx.compose.ui.graphics.colorspace.o.(java.lang.Object): [0x0] cannot access instance field java.lang.Object androidx.compose.ui.graphics.colorspace.n.a from object of type Precise Reference: androidx.compose.ui.graphics.colorspace.o
Android Gradle 外掛程式 7.4.0/7.3.1 - 嘗試在不可推送的佇列工作清單中將動作排入佇列
壓縮 Renderscript 程式碼:將 AGP 從 7.3.1 升級到 7.4.0 時效能顯著下降

Android Gradle 外掛程式 8.0.1 版

已修正問題
縮減器 (R8)
從 AGP 7.2.2 升級到 7.4.0 後,出現「No VersionRequirement with the given id in the table」錯誤
markTypeAsLive AGP 7.4.1 發生 R8 NullPointerException
[R8 4.0.53] Android 11 發生類別驗證失敗的嚴重問題

Android Gradle 外掛程式 8.0.2 版

已修正問題
縮減器 (R8)
R8 在 Compose 構建期間失敗並顯示 ArrayIndexOutOfBoundsException
VerifyError:搭配 Kotlin 1.8.20 使用 R8 時,類別遭驗證器拒絕
AGP 8 上的 R8 會中斷 Google Fit 服務
來源檔案資訊中剩餘的名稱如與輸入名稱重疊,加入這些資訊後將無法正確顯示