Android Gradle 外掛程式搶先版版本資訊

本頁面提供 Android Gradle 外掛程式 (AGP) 預先發布版本的版本資訊。

Android Gradle 外掛程式 9.0 版

Android Gradle 外掛程式 9.0 是 AGP 的新主要版本，並帶來 API 和行為變更。

如要更新至 Android Gradle 外掛程式 9.0.0-alpha11，請在 Android Studio Otter 2 Feature Drop | 2025.2.2 中使用 Android Gradle 外掛程式升級工具。

升級專案時，AGP 升級小幫手會盡可能保留現有行為，讓您將專案升級為使用 AGP 9.0，即使您尚未準備好採用 AGP 9.0 的所有新預設值，也能順利升級。

相容性

Android Gradle 外掛程式 9.0.0-alpha11 支援的最高 Android API 級別為 API 級別 36。

Android Gradle 外掛程式 9.0.0-alpha11 需要 Gradle 9.0.0。

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

過去幾年，我們為 DSL 和 API 推出新介面，以便更妥善控管公開 API。AGP 7.x 和 8.x 版仍使用舊版 DSL 型別 (例如 BaseExtension)，這些型別也實作了新的公開介面，以便在介面開發期間維持相容性。

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

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

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

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

• 更新建構檔案： 雖然介面變更的目的是盡可能保留 DSL，但可能還是會出現一些小變更。

• 更新自訂建構邏輯，以參照新的 DSL 和 API： 將所有內部 DSL 的參照項目，替換為公開 DSL 介面。 在大多數情況下，這會是一對一的更換。 請將所有使用 applicationVariants 和類似 API 的位置，都換成新的 androidComponents API。這可能較為複雜，因為 androidComponents API 的設計目的是為了提高穩定性，讓外掛程式能維持更久的相容性。如需範例，請參閱「Gradle Recipes」。

• 更新第三方外掛程式： 部分第三方外掛程式可能仍依附於不再公開的介面或 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

您也可以先升級至新版 API，再升級至 AGP 9.0。新介面已存在於許多 AGP 版本中，因此您可以混用新舊介面。AGP API 參考文件會顯示各個 AGP 版本的 API 介面，以及新增各個類別、方法和欄位的時間。

在 9.0 版的 Alpha 階段，我們會與外掛程式作者聯絡，協助他們調整及發布與新模式完全相容的外掛程式，並強化 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 外掛程式 2.2.10

Android Gradle 外掛程式 9.0 在執行階段會依附於 Kotlin Gradle 外掛程式 (KGP) 2.2.10，這是內建 Kotlin 支援所需的最低版本。

也就是說，如果您選擇停用內建 Kotlin，並使用低於 2.2.10 的 KGP 版本，Gradle 會自動將 KGP 版本升級至 2.2.10。

同樣地，如果您使用的 KSP 版本低於 2.2.10-2.0.2，AGP 會將 KSP 版本升級至 2.2.10-2.0.2，以配合 KGP 版本。

因此，如果您選擇停用內建 Kotlin，並想使用舊版 KGP 或 KSP，請在頂層建構檔案中新增下列項目：

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

IDE 支援測試固件

AGP 9.0 針對測試固定裝置，提供完整的 Android Studio IDE 支援。如要取得這項支援，請使用 AGP 9.0.0-alpha07 以上版本。

行為變更

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

AGP 9.0 包含下列 Gradle 屬性預設值的更新。這樣您在升級時，就能選擇保留 AGP 8.13 行為：

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 報告工作

已變更的 DSL

Android Gradle 外掛程式 9.0 版的 DSL 破壞性變更如下：

• 已移除 CommonExtension 的參數化。

  就本身而言，這只是來源層級的重大變更，有助於避免日後發生來源層級的重大變更，但也表示區塊方法需要從 CommonExtension 移至 ApplicationExtension、LibraryExension、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 屬性取代

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

已移除的 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。

已修正問題

Android Gradle 外掛程式 9.0.0-alpha10

Android Gradle 外掛程式 9.0.0-alpha09

Android Gradle 外掛程式 9.0.0-alpha08

Android Gradle 外掛程式 9.0.0-alpha07

Android Gradle 外掛程式 9.0.0-alpha06

Android Gradle 外掛程式 9.0.0-alpha05

Android Gradle 外掛程式 9.0.0-alpha04

Android Gradle 外掛程式 9.0.0-alpha03

Android Gradle 外掛程式 9.0.0-alpha02

Android Gradle 外掛程式 9.0.0-alpha01