Android Gradle 外掛程式 9.0.1 版 (2026 年 1 月)

Android Gradle 外掛程式 9.0 是主要版本，會變更 API 和行為。

如要更新至 Android Gradle 外掛程式 9.0.1，請使用 Android Gradle 外掛程式升級工具。AGP 升級輔助程式會在適當情況下，協助您在升級專案時保留現有行為，因此即使您尚未準備好採用 AGP 9.0 的所有新預設值，仍可將專案升級至 AGP 9.0。

此外，您也可以使用兩項代理技能，簡化升級程序。如果是非 KMP 應用程式，請嘗試使用 Android 技能存放區中的 AGP 9 升級技能。如果是 KMP 應用程式，請嘗試使用 JetBrains 的 AGP 9 升級技能。如要進一步瞭解如何在 Android Studio 中使用技能，請參閱「使用技能擴充代理模式」。

相容性

Android Gradle 外掛程式 9.0 支援的最高 API 級別為 36.1。其他相容性資訊如下：

android DSL 類別現在只會實作新的公開介面

過去幾年來，我們為 DSL 和 API 導入了新介面，以便進一步控管哪些 API 為公開。AGP 7.x 和 8.x 版仍使用舊的 DSL 類型 (例如 BaseExtension)，這些類型也實作了新的公開介面，以便在介面開發期間維持相容性。

AGP 9.0 僅使用新的 DSL 介面，且實作項目已變更為完全隱藏的新類型。這也會移除舊版已淘汰 Variant API 的存取權。

如要更新至 AGP 9.0，您可能需要執行下列操作：

• 確保專案與內建 Kotlin 相容：org.jetbrains.kotlin.android 外掛程式與新版 DSL 不相容。

• 將 KMP 專案切換至 KMP 適用的 Android Gradle 程式庫外掛程式：在與 com.android.library 和 com.android.application 外掛程式相同的 Gradle 子專案中使用 org.jetbrains.kotlin.multiplatform 外掛程式，與新的 DSL 不相容。

• 更新建構檔案：雖然介面變更旨在盡可能保持 DSL 相似，但可能會有一些小變更。

• 更新自訂建構邏輯，參照新的 DSL 和 API： 將所有內部 DSL 參照替換為公開 DSL 介面。在大多數情況下，這會是一對一的替換。請改用新的 androidComponents API，取代 applicationVariants 和類似 API。這可能較為複雜，因為 androidComponents API 的設計更穩定，可讓外掛程式相容更久。如需範例，請參閱 Gradle 秘訣。

• 更新第三方外掛程式：部分第三方外掛程式可能仍依賴不再公開的介面或 API。請改用與 AGP 9.0 相容的外掛程式版本。

改用新版 DSL 介面後，外掛程式和 Gradle 建構指令碼就不會使用各種已淘汰的 API，包括：

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

如果您更新至 AGP 9.0，並看到下列錯誤訊息，表示專案仍參照部分舊類型：

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

如果因不相容的第三方外掛程式而無法使用，您可以選擇停用，並還原 DSL 的舊版實作和舊版變體 API。在此期間，您也可以使用新介面，並將建構邏輯更新為新版 API。如要停用，請在 gradle.properties 檔案中加入以下這行：

android.newDsl=false

或者，如要逐步遷移，AGP 9.4 可讓您選擇不採用個別模組。如要瞭解如何操作，請參閱「Variant API 模組選擇不採用」。

在 AGP 9.0 中，先前的類別會標示為已淘汰。也就是說，如果專案選擇不採用 newDsl 旗標，就會看到淘汰警告，包括 android 區塊本身。

您也可以在升級至 AGP 9.0 之前，先開始升級至新版 API。新介面已在多個 AGP 版本中推出，因此您可以混合使用新舊介面。AGP API 參考資料會顯示每個 AGP 版本的 API 介面，以及各類別、方法和欄位的新增時間。

我們正與常用外掛程式的作者聯絡，協助他們調整及發布與新模式完全相容的外掛程式，並會繼續強化 Android Studio 中的 AGP 升級助理，引導您完成遷移。

如果您發現新的 DSL 或 Variant API 缺少功能，請盡快提出問題。

內建 Kotlin

Android Gradle 外掛程式 9.0 導入內建 Kotlin 支援，並預設啟用。也就是說，您不必再於建構檔案中套用 org.jetbrains.kotlin.android (或 kotlin-android) 外掛程式，即可編譯 Kotlin 來源檔案。這可簡化 Kotlin 與 AGP 的整合、避免使用已淘汰的 API，並在某些情況下提升效能。

因此，將專案升級至 AGP 9.0 時，您也需要遷移至內建 Kotlin 或選擇不採用。

您也可以針對沒有 Kotlin 來源的 Gradle 子專案，選擇性停用內建 Kotlin 支援。

Kotlin Gradle 外掛程式的執行階段依附元件

為提供內建 Kotlin 支援，Android Gradle 外掛程式 9.0 現在對 Kotlin Gradle 外掛程式 (KGP) 2.2.10 有執行階段依附元件。也就是說，您不必再宣告 KGP 版本，如果您使用的 KGP 版本低於 2.2.10，Gradle 會自動將 KGP 版本升級至 2.2.10。同樣地，如果您使用的 KSP 版本低於 2.2.10-2.0.2，AGP 會將其升級至 2.2.10-2.0.2，以符合 KGP 版本。

升級至更高 KGP 版本

如要使用更高版本的 KGP 或 KSP，請在頂層建構檔案中加入以下內容：

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtools.ksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

降級至較低的 KGP 版本

只有在選擇不採用內建 Kotlin 時，才能降級 KGP 版本。這是因為 AGP 9.0 預設會啟用內建 Kotlin，而內建 Kotlin 需要 KGP 2.2.10 以上版本。

如要使用較低版本的 KGP 或 KSP，請在頂層建構檔案中，使用嚴格版本宣告該版本：

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtools.ksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

請注意，可降級的最低 KGP 版本為 2.0.0。

IDE 支援測試固件

AGP 9.0 為測試固件提供完整的 Android Studio IDE 支援。

Fused Library 外掛程式

Fused Library Plugin (預先發布版) 可讓您將多個程式庫發布為單一 Android 程式庫 AAR。這樣一來，使用者就能更輕鬆地依賴您發布的構件。

如要瞭解如何開始使用，請參閱「使用 Fused Library 將多個 Android 程式庫合併發布」。

行為變更

Android Gradle 外掛程式 9.0 具有下列新行為：

AGP 9.0 更新了下列 Gradle 屬性的預設值。因此，您可以在升級時選擇保留 AGP 8.13 行為：

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

已移除的功能

Android Gradle 外掛程式 9.0 移除下列功能：

• 內嵌 Wear OS 應用程式支援
  AGP 9.0 移除內嵌 Wear OS 應用程式的支援，Play 不再支援這項功能。包括移除 wearApp 設定和 AndroidSourceSet.wearAppConfigurationName DSL。如要瞭解如何將應用程式發布至 Wear OS，請參閱「發布至 Wear OS」。
• androidDependencies 和 sourceSets 報表工作
• 支援密度分割 APK
  AGP 9.0 不再支援根據螢幕密度建立分割 APK。這項功能和相關 API 已移除。如要使用 AGP 9.0 以上版本，根據螢幕密度分割 APK，請使用應用程式套件。

已變更 DSL

Android Gradle 外掛程式 9.0 包含下列破壞性 DSL 變更：

• CommonExtension 的參數化功能已移除。

  就本身而言，這只是來源層級的破壞性變更，有助於避免日後發生來源層級的破壞性變更，但也意味著區塊方法必須從 CommonExtension 移至 ApplicationExtension、LibraryExtension、DynamicFeatureExtension 和 TestExtension。

  將專案升級至 AGP 9.0 時，請重構使用這些參數或區塊方法的 Gradle 外掛程式程式碼。舉例來說，下列外掛程式已更新，可移除類型參數，且不依賴已移除的區塊方法：

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  如果外掛程式指定多個 AGP 版本，直接使用 getter 的二進位檔與 9.0 以下的 AGP 版本相容。

已移除 DSL

Android Gradle 外掛程式 9.0 移除：

• AndroidSourceSet.jni，因為無法正常運作。

• AndroidSourceSet.wearAppConfigurationName，因為這與移除內嵌 Wear OS 應用程式支援有關。

• BuildType.isRenderscriptDebuggable，因為無法正常運作。

• DependencyVariantSelection。由 DependencySelection 取代，並公開為 kotlin.android.localDependencySelection

• Installation.installOptions(String)。它已由 Installation.installOptions 的可變動屬性取代。

• 實驗性但從未穩定的 PostProcessing 區塊。

• ProductFlavor.setDimension，由 dimension 屬性取代

• LanguageSplitOptions，這項功能僅適用於已淘汰的 Google Play 免安裝。

• DensitySplit，因為系統不再支援這項功能。請改用應用程式套件。

已移除的 API

Android Gradle 外掛程式 9.0 移除：

• AndroidComponentsExtension.finalizeDSl。已由 finalizeDsl 取代

• Component.transformClassesWith。已由 Instrumentation.transformClassesWith 取代

• Component.setAsmFramesComputationMode。已由 Instrumentation.setAsmFramesComputationMode 取代

• ComponentBuilder.enabled：由 ComponentBuilder.enable 取代。

• DependenciesInfoBuilder.includedInApk。已由 includeInApk 取代

• DependenciesInfoBuilder.includedInBundle。已由 includeInBundle 取代

• GeneratesApk.targetSdkVersion：已由 targetSdk 取代

• Variant.minSdkVersion：已由 minSdk 取代

• Variant.maxSdkVersion：已由 maxSdk 取代

• Variant.targetSdkVersion：已由 targetSdk 取代

• Variant.unitTest，因為不適用於 com.android.test 外掛程式。unitTest 適用於擴充 HasUnitTest 的 VariantBuilder 子類型。

• VariantBuilder.targetSdk 和 targetSdkPreview，因為這些在程式庫中沒有意義。請改用 GeneratesApkBuilder.targetSdk 或 GeneratesApkBuilder.targetSdkPreview。

• VariantBuilder.enableUnitTest，因為不適用於 com.android.test 外掛程式。enableUnitTest 適用於擴充 HasUnitTestBuilder 的 VariantBuilder 子類型。

• VariantBuilder.unitTestEnabled 已移除，改用命名更一致的 enableUnitTest，用於擴充 HasUnitTestBuilder 的 VariantBuilder 子類型。

• VariantOutput.enable：已由 enabled 取代

• 已淘汰並停用的 FeaturePlugin 和 FeatureExtension。

• 已淘汰並停用的 BaseExtension.registerTransform API，僅保留用於允許針對最新 AGP 版本進行編譯，同時指定在 AGP 4.2 以下版本上執行。

已移除 Gradle 屬性

下列 Gradle 屬性最初新增時，是用來全域停用預設啟用的功能。

自 AGP 8.0 或更低版本起，這些功能預設為停用。請只在會用到這些功能的子專案中啟用，建構作業會更有效率。

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

強制執行的 Gradle 屬性

如果您設定下列 Gradle 屬性，AGP 9.0 會擲回錯誤。

Android Gradle 外掛程式升級小幫手不會將使用這些屬性的專案升級至 AGP 9.0。

R8 變更

AGP 9.0.0 包含下列 R8 變更。

新設定選項 -processkotlinnullchecks

我們新增了 R8 選項 -processkotlinnullchecks，可設定 R8 處理 Kotlin 空值檢查。這個選項會採用必要引數，且必須是下列三個值之一：keep、remove_message 和 remove。這個選項會處理 Kotlin 編譯器新增的下列空值檢查：

class kotlin.jvm.internal.Intrinsics {
  void checkNotNull(java.lang.Object);
  void checkNotNull(java.lang.Object, java.lang.String);
  void checkExpressionValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkNotNullExpressionValue(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkFieldIsNotNull(java.lang.Object, java.lang.String);
  void checkFieldIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkParameterIsNotNull(java.lang.Object, java.lang.String);
  void checkNotNullParameter(java.lang.Object, java.lang.String);
}

選項值由弱到強排序，效果如下：

• keep 不會變更檢查。
• remove_message 會將每個檢查方法呼叫，重寫為對呼叫的第一個引數呼叫 getClass() (有效保留空值檢查，但沒有任何訊息)。
• remove 會完全移除檢查。

根據預設，R8 會使用 remove_message。任何 -processkotlinnullchecks 規格都會覆寫該值。如果指定多次，系統會使用最強的值。

停止將保留資訊傳播至隨附方法

當保留規則與需要脫糖的介面方法相符時，R8 先前會在內部將「不允許最佳化」和「不允許縮減」位元轉移至合成隨附方法。

從 AGP 9.0 開始，保留規則不再適用於隨附方法。這與保留規則不適用於其他編譯器合成欄位/方法/類別的事實一致。

將「不允許最佳化」和「不允許縮減」位元轉移至隨附方法後，先前支援以下用途：

1. 使用 default/static/private 介面方法將程式庫編譯為 DEX，其中 minSdk < 24，且規則會保留介面方法。
2. 使用類別路徑和 -applymapping 上的程式庫編譯應用程式。
3. 合併應用程式和程式庫。

請注意，這項功能僅適用於 -applymapping，因為 disallow obfuscation 位元不會轉移至伴隨方法，也就是說，從步驟 1 產生的伴隨類別會有名稱經過模糊處理的方法。

日後，minSdk < 24 將不再支援這項用途。解決方法如下：

1. 使用 default/static/private 介面方法，將程式庫脫糖至 minSdk < 24 的類別檔案。
2. 使用 R8 和規則編譯脫糖構件，在隨附類別中保留介面方法。
3. 使用 classpath 上的程式庫編譯應用程式。
4. 合併應用程式和脫糖構件。

這項異動的另一個副作用是，無法再保留介面伴生物件方法中匿名和本機類別的內部類別和封閉方法屬性。

將預設發出的來源檔案變更為 r8-map-id-<MAP_ID>

這項異動自 AGP 8.12.0 起生效。

需要重新追蹤時 (也就是啟用模糊處理或最佳化時)，類別的預設發出來源檔案屬性會從 SourceFile 變更為 r8-map-id-<MAP_ID>。

如果堆疊追蹤經過模糊處理，新的來源檔案屬性可擷取反向追蹤所需的對應檔案 ID，用於支援在 Logcat 中自動反向追蹤堆疊追蹤。

如果使用自訂來源檔案屬性 (-renamesourcefileattribute)，則該屬性仍會優先採用。

在 ProGuard 相容模式下 (gradle.properties 包含 android.enableR8.fullMode=false 時)，只有在未保留 SourceFile 屬性的情況下，發出 r8-map-id-<MAP_ID> 的來源檔案屬性才會生效。如果應用程式使用 ProGuard 相容模式，且想在堆疊追蹤中加入對應檔案 ID，應移除 -keepattributes SourceFile (或遷移至 R8 完整模式)。

r8-map-id-<MAP_ID> 中使用的對應 ID 是完整的對應雜湊，而非先前使用的 7 個字元前置字串。

在 L8 脫糖中啟用縮減合成名稱

D8 產生的合成類別名稱通常包含子字串 $$ExternalSynthetic，表示這是 D8 產生的合成類別。此外，合成名稱也會對合成種類進行編碼 (例如 Backport、Lambda)。這會對產生的 DEX 大小造成負面影響，因為類別名稱會占用字串集區中的更多空間。

AGP 9.0 會設定 L8 (核心程式庫脫糖)，讓包含所有 j$ 類別的 DEX 檔案，對合成類別使用新的縮短類別名稱格式。新類別名稱會使用數字 ID (例如 $1)。

移除對 -addconfigurationdebugging 的支援

AGP 9.0 不再支援 -addconfigurationdebugging。如果使用這個旗標，編譯器現在會回報警告。

移除從 D8/R8 產生 L8 規則的支援

這項異動僅適用於直接使用 D8/R8 指令列或 API 的開發人員。

R8 9.0 停止支援從 D8 和 R8 為 L8 產生保留規則。請改用 TraceReferences。

具體來說，D8Command.builder.setDesugaredLibraryKeepRuleConsumer 和 R8Command.Builder.setDesugaredLibraryKeepRuleConsumer 方法已移除，且 D8 和 R8 的指令列選項不再支援 --desugared-lib-pg-conf-output。

已修正問題

Android Gradle 外掛程式 9.0.0