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

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

Android Gradle 外掛程式 9.0 版

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

如要更新至 Android Gradle 外掛程式 9.0.0-alpha10，請在 Android Studio Otter | 2025.2.1 中使用 Android Gradle 外掛程式升級工具。

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

相容性

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

Android Gradle 外掛程式 9.0.0-alpha10 版需要 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 編譯支援，可取代另外套用的 Kotlin 外掛程式。這項功能可簡化與 AGP 的整合，避免使用已淘汰的 API，並在某些情況下提升效能。

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

AGP 9.0 內建 Kotlin，可為 test-fixtures 提供完整的 Android Studio IDE 支援。如要試用這項功能，請使用 AGP 9.0.0-alpha07 以上版本。

您可以設定 android.builtInKotlin=false，停用內建的 Kotlin。

如果您已停用內建的 Kotlin，且需要使用舊版 Kotlin Gradle 外掛程式，可以強制降級：

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

行為變更

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