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

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

Android Gradle 外掛程式 9.0 版

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

如要更新至 Android Gradle 外掛程式 9.0.0-alpha04，請在 Android Studio Narwhal 4 Feature Drop | 2025.1.4 中使用 Android Gradle 外掛程式升級工具。

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

相容性

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

Android Gradle 外掛程式 9.0.0-alpha04 版需要 Gradle 9.0.0 版。

內部 DSL 實作項目和已淘汰的變數 API 現在需要明確選擇加入

Android Gradle 外掛程式現在已定義 API 介面，支援的 API 定義於 com.android.tools.build:gradle-api Maven 構件中。

為了與現有的二進位外掛程式和建構指令碼相容，在 AGP 8.13 以下版本中，系統預設仍會公開定義 API 途徑之前的舊版 DSL 實作項目。這樣一來，Gradle 外掛程式和建構指令碼中的程式碼，就能存取 DSL 的內部實作詳細資料，以及已淘汰的 android.applicationVariants、android.libraryVariants、android.testVariants 和 android.unitTestVariants API (這些 API 將在 2026 年的 AGP 10 中移除)。

為讓這項轉換更明顯，Android Gradle 外掛程式 9.0.0-alpha04 預設不會提供舊版變數 API 和內部 DSL。

如要重新使用已淘汰的 API，請在 gradle.properties 中設定 android.newDsl=false。

在 9.0 版 Alpha 系列期間，我們會與外掛程式作者聯絡，協助他們調整及發布與新模式完全相容的外掛程式，並強化 Android Studio 中的 AGP 升級助理，引導您完成遷移作業。

內建 Kotlin

Android Gradle 外掛程式 9 內建支援 Kotlin 編譯功能，可取代另外套用的 Kotlin 外掛程式。這項功能可簡化與 AGP 的整合，避免使用已淘汰的 API，並在某些情況下提升效能。

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

如要停用內建的 Kotlin，請設定 android.builtInKotlin=false。 如果您已選擇退出，且需要使用舊版 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 {
    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，因為該功能無法運作。

• ComponentBuilder.enabled。這項功能已由 ComponentBuilder.enable 取代。

• DependencyVariantSelection。已替換為 DependencySelection，後者會公開為 kotlin.android

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

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

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

• ProductFlavor.setDimension，已由 dimension 屬性取代

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

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

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

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

已移除的 Gradle 屬性

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

自 AGP 8.0 以下版本起，這些功能預設為停用。只在需要使用這些功能的子專案中啟用，以提高建構效率。

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

已移除的 API

Android Gradle 外掛程式 9.0 移除的項目：

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

強制執行的 Gradle 屬性

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

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