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 制品中。

为了与现有的二进制插件和 build 脚本兼容，在 AGP 8.13 及更低版本中，默认情况下仍会公开定义该 API 接口之前的 DSL 实现。这样一来，Gradle 插件和 build 脚本中的代码就可以访问 DSL 的内部实现详细信息以及已弃用的 android.applicationVariants、android.libraryVariants、android.testVariants 和 android.unitTestVariants API，这些 API 将在 2026 年的 AGP 10 中移除。

为了让这种过渡更加明显，从 Android Gradle 插件 9.0.0-alpha04 开始，默认情况下无法访问旧版变体 API 和内部 DSL。

您可以在 gradle.properties 中设置 android.newDsl=false，重新选择使用已弃用的 API。

在 9.0 Alpha 版系列期间，我们会联系插件作者，帮助他们调整并发布与新模式完全兼容的插件，并增强 Android Studio 中的 AGP 升级助理，以引导您完成迁移。

内置 Kotlin

Android Gradle 插件 9 包含用于编译 Kotlin 的内置支持，取代了单独应用的 Kotlin 插件。这简化了与 AGP 的集成，避免使用已废弃的 API，并在某些情况下提高了性能。

Android Gradle 插件 9 在运行时依赖于 Kotlin Gradle 插件 2.2.0，这是内置 Kotlin 支持所需的最低版本。

您可以通过设置 android.builtInKotlin=false 来选择停用内置 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 {
    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 的形参化。 就其本身而言，这只是一个源代码级破坏性变更，旨在帮助避免未来出现源代码级破坏性变更，但这也意味着 DSL 块方法需要从 CommonExtension 移至 ApplicationExtension、LibraryExension、DynamicFeatureExtension 和 TestExtension。

移除了 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 属性取代

• 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 版本进行编译。

强制执行的 Gradle 属性

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

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