Android Gradle 插件预览版版本说明

本页面包含 Android Gradle 插件 (AGP) 预览版的版本说明。

Android Gradle 插件 9.0

Android Gradle 插件 9.0 是 AGP 的一个全新主要版本，带来了 API 和行为变更。

如需更新到 Android Gradle 插件 9.0.0-alpha05，请在 Android Studio Narwhal 4 Feature Drop | 2025.1.4 中使用 Android Gradle 插件升级助理。

AGP 升级助理有助于在升级项目时尽可能保留现有行为，即使您尚未准备好采用 AGP 9.0 中的所有新默认设置，也可以将项目升级为使用 AGP 9.0。

兼容性

Android Gradle 插件 9.0.0-alpha05 支持的最高 Android API 级别为 API 级别 36。

Android Gradle 插件 9.0.0-alpha05 需要 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 不兼容。

• 更新 build 文件：虽然接口的更改旨在尽可能保持 DSL 的相似性，但可能存在一些细微的更改。

• 更新自定义 build 逻辑以引用新的 DSL 和 API： 将对内部 DSL 的所有引用替换为公共 DSL 接口。 在大多数情况下，这会是一对一的替换。 将所有使用 applicationVariants 和类似 API 的情况替换为新的 androidComponents API。这可能更复杂，因为 androidComponents API 的设计旨在提高稳定性，以使插件能够更长时间地保持兼容。如需查看示例，请参阅我们的 Gradle 诀窍。

• 更新第三方插件：某些第三方插件可能仍依赖于不再公开的接口或 API。迁移到与 AGP 9.0 兼容的插件版本。

如果您更新到 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。在此过程中，新接口也可用，您仍然可以将自己的 build 逻辑更新为新 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 支持所需的最低版本。

您可以通过设置 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 移除了以下内容：

• AndroidComponentsExtension.finalizeDSl。它已被 finalizeDsl 取代

• AndroidSourceSet.jni，因为该功能无法正常运行。

• AndroidSourceSet.wearAppConfigurationName，因为这与已移除的嵌入式 Wear OS 应用支持有关。

• BuildType.isRenderscriptDebuggable，因为该功能无法正常运行。

• Component.transformClassesWith。它已被 Instrumentation.transformClassesWith 取代

• Component.setAsmFramesComputationMode。它已被 Instrumentation.setAsmFramesComputationMode 取代

• DependenciesInfoBuilder.includedInApk。已替换为 includeInApk

• DependenciesInfoBuilder.includedInBundle。已替换为 includeInBundle

• ComponentBuilder.enabled。它已被 ComponentBuilder.enable 取代。

• DependencyVariantSelection。它已替换为 DependencySelection，后者以 kotlin.android 的形式公开

• GeneratesApk.targetSdkVersion。已替换为 targetSdk

• Installation.installOptions(String)。它已被 Installation.installOptions 的可变属性取代。

• Variant.minSdkVersion。已替换为 minSdk

• Variant.maxSdkVersion。已替换为 maxSdk

• Variant.targetSdkVersion。已替换为 targetSdk

• VariantBuilder.targetSdk 和 targetSdkPreview，因为它们在库中没有意义。请改用 GeneratesApkBuilder.targetSdk 或 GeneratesApkBuilder.targetSdkPreview。

• VariantOutput.enable。已替换为 enabled

• 实验性但从未稳定过的 PostProcessing 块。

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

• LanguageSplitOptions，该属性仅对已弃用的 Google Play 免安装体验有用。

• Variant.unitTest，因为它不适用于 com.android.test 插件。 unitTest 可用于扩展 HasUnitTest 的 VariantBuilder 子类型。

• VariantBuilder.enableUnitTest，因为它不适用于 com.android.test 插件。 enableUnitTest 可用于扩展 HasUnitTestBuilder 的 VariantBuilder 子类型。

• 移除了 VariantBuilder.unitTestEnabled，取而代之的是在扩展 HasUnitTestBuilder 的 VariantBuilder 子类型上更一致命名的 enableUnitTest。

已移除的 Gradle 属性

以下 Gradle 属性最初添加的目的是为了全局停用默认启用的功能。

自 AGP 8.0 或更低版本以来，这些功能已默认停用。仅在使用这些功能的子项目中启用它们，以提高构建效率。

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

已移除的 API

Android Gradle 插件 9.0 移除了以下内容：

• 已废弃并停用的 BaseExtension.registerTransform API，这些 API 仅用于在以 AGP 4.2 或更低版本为目标平台的同时，允许针对最新 AGP 版本进行编译。

• 已弃用并停用的 FeaturePlugin 和 FeatureExtension。

强制执行的 Gradle 属性

如果您设置了以下 Gradle 属性，AGP 9.0 会抛出错误。

Android Gradle 插件升级助理不会将使用这些属性的项目升级到 AGP 9.0。