Android Gradle 插件 9.0.1（2026 年 1 月）

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

如需更新到 Android Gradle 插件 9.0.1，请使用 Android Gradle 插件升级助理。AGP 升级助理会在适当的时候帮助您在升级项目时保留现有行为，因此即使您尚未准备好采用 AGP 9.0 中的所有新默认设置，也可以升级项目以使用 AGP 9.0。

此外，还有两项智能体技能可让升级过程更轻松。 对于非 KMP 应用，请尝试使用 Android 技能代码库中的 AGP 9 升级技能。对于 KMP 应用，请尝试使用 JetBrains 提供的 AGP 9 升级技能。如需详细了解如何在 Android Studio 中使用技能，请参阅使用技能扩展智能体模式。

兼容性

Android Gradle 插件 9.0 支持的最高 API 级别为 API 级别 36.1。 以下是更多兼容性信息：

android DSL 类现在仅实现新的公共接口

在过去几年中，我们为 DSL 和 API 引入了新接口，以便更好地控制哪些 API 是公开的。AGP 7.x 和 8.x 版仍使用旧 DSL 类型（例如 BaseExtension），这些类型也实现了新的公共接口，以便在接口开发过程中保持兼容性。

AGP 9.0 仅使用我们的新 DSL 接口，并且实现已更改为完全隐藏的新类型。这也会移除对已弃用的旧版 Variant API 的访问权限。

如需更新到 AGP 9.0，您可能需要执行以下操作：

• 确保您的项目与内置 Kotlin 兼容：org.jetbrains.kotlin.android 插件与新 DSL 不兼容。

• 将 KMP 项目切换到适用于 KMP 的 Android Gradle 库插件：在与 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 兼容的插件版本。

切换到新的 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 的旧实现以及旧版 Variant API。 在此期间，新接口也可用，您仍然可以将自己的 build 逻辑更新为新 API。如需停用，请在 gradle.properties 文件中添加以下行：

android.newDsl=false

或者，为了更渐进地迁移，AGP 9.4 允许您选择停用单个模块。如需了解具体方法，请参阅选择退出 Variant API 模块。

在 AGP 9.0 中，之前的类会被标记为已废弃。这意味着，选择停用 newDsl 标志的项目将看到弃用警告，包括在 android 代码块本身上。

您也可以在升级到 AGP 9.0 之前，先开始升级到新 API。新接口已在许多 AGP 版本中提供，因此您可以混合使用新旧接口。AGP API 参考文档显示了每个 AGP 版本的 API Surface，以及每个类、方法和字段的添加时间。

我们正在与常用插件的作者联系，帮助他们调整和发布与新模式完全兼容的插件，并将继续增强 Android Studio 中的 AGP 升级助理，以指导您完成迁移。

如果您发现新的 DSL 或 Variant API 缺少某些功能，请尽快提交问题。

内置 Kotlin

Android Gradle 插件 9.0 引入了内置 Kotlin 支持，并默认启用。这意味着，您无需再在 build 文件中应用 org.jetbrains.kotlin.android（或 kotlin-android）插件来编译 Kotlin 源文件。 这简化了 Kotlin 与 AGP 的集成，避免了使用已废弃的 API，并在某些情况下提高了性能。

因此，在将项目升级到 AGP 9.0 时，您还需要迁移到内置 Kotlin 或选择停用。

您还可以为没有 Kotlin 源代码的 Gradle 子项目选择性地停用内置 Kotlin 支持。

对 Kotlin Gradle 插件的运行时依赖

为了提供内置 Kotlin 支持，Android Gradle 插件 9.0 现在对 Kotlin Gradle 插件 (KGP) 2.2.10 具有运行时依赖项。这意味着您不再需要声明 KGP 版本，并且如果您使用的 KGP 版本低于 2.2.10，Gradle 会自动将您的 KGP 版本升级到 2.2.10。 同样，如果您使用的 KSP 版本低于 2.2.10-2.0.2，AGP 会将其升级到 2.2.10-2.0.2，以匹配 KGP 版本。

升级到更高的 KGP 版本

如需使用更高版本的 KGP 或 KSP，请将以下内容添加到顶级 build 文件中：

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtools.ksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

降级到较低的 KGP 版本

只有在选择停用内置 Kotlin 的情况下，您才能降级 KGP 版本。 这是因为 AGP 9.0 默认启用内置 Kotlin，而内置 Kotlin 需要 KGP 2.2.10 或更高版本。

如需使用较低版本的 KGP 或 KSP，请在顶级 build 文件中使用严格版本声明来声明该版本：

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtools.ksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

请注意，您可以降级到的最低 KGP 版本为 2.0.0。

IDE 支持测试固件

AGP 9.0 为测试固件提供了完整的 Android Studio IDE 支持。

融合库插件

借助 Fused Library 插件（预览版），您可以将多个库作为一个 Android 库 AAR 发布。这样，用户可以更轻松地依赖您发布的工件。

如需了解如何开始使用，请参阅使用 Fused Library 将多个 Android 库作为一个库发布。

行为变更

Android Gradle 插件 9.0 具有以下新行为：

AGP 9.0 更新了以下 Gradle 属性的默认值。 这样，您就可以在升级时选择保留 AGP 8.13 的行为：

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

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 报告任务
• 密度拆分 APK 支持
  AGP 9.0 移除了对基于屏幕密度创建拆分 APK 的支持。该功能和相关 API 已被移除。如需使用 AGP 9.0 或更高版本根据屏幕密度拆分 APK，请使用 app bundle。

更改了 DSL

Android Gradle 插件 9.0 包含以下破坏性 DSL 变更：

• CommonExtension 的形参化已被移除。

  就其本身而言，这只是一个源代码级破坏性更改，旨在帮助避免未来发生源代码级破坏性更改，但这也意味着块方法需要从 CommonExtension 移至 ApplicationExtension、LibraryExtension、DynamicFeatureExtension 和 TestExtension。

  将项目升级到 AGP 9.0 时，请重构使用这些参数或块方法的 Gradle 插件代码。例如，以下插件已更新，以移除 type 参数，并且不依赖于已移除的块方法：

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

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

• DensitySplit，因为该功能不再受支持。 替代方案是使用 App Bundle。

已移除的 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，改为在扩展 HasUnitTestBuilder 的 VariantBuilder 子类型上使用命名更一致的 enableUnitTest。

• VariantOutput.enable。它已被 enabled 替换

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

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

已移除 Gradle 属性

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

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

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

强制执行的 Gradle 属性

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

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

R8 变更

AGP 9.0.0 包含以下 R8 变更。

新配置选项 -processkotlinnullchecks

我们添加了新的 R8 选项 -processkotlinnullchecks，用于配置 R8 以处理 Kotlin null 检查。该选项接受一个必需参数，该参数必须是以下三个值之一：keep、remove_message 和 remove。该选项会处理 Kotlin 编译器添加的以下 null 检查：

class kotlin.jvm.internal.Intrinsics {
  void checkNotNull(java.lang.Object);
  void checkNotNull(java.lang.Object, java.lang.String);
  void checkExpressionValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkNotNullExpressionValue(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String);
  void checkReturnedValueIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkFieldIsNotNull(java.lang.Object, java.lang.String);
  void checkFieldIsNotNull(
      java.lang.Object, java.lang.String, java.lang.String);
  void checkParameterIsNotNull(java.lang.Object, java.lang.String);
  void checkNotNullParameter(java.lang.Object, java.lang.String);
}

选项值按从最弱到最强的顺序排列，具有以下效果：

• keep 不会更改检查。
• remove_message 会将每个检查方法调用重写为对调用的第一个参数调用 getClass()（实际上保留了 null 检查，但没有任何消息）。
• remove 会完全移除这些检查。

默认情况下，R8 使用 remove_message。任何 -processkotlinnullchecks 规范都会覆盖该规范。如果多次指定，则使用最强的值。

停止将保留信息传播到伴随方法

当 keep 规则与需要脱糖的接口方法匹配时，R8 之前会在内部将禁止优化和禁止缩减位转移到合成的伴随方法。

从 AGP 9.0 开始，保留规则不再适用于伴生方法。这与保留规则不适用于其他编译器合成的字段/方法/类这一事实一致。

通过将禁止优化和禁止缩减位转移到配套方法，之前支持以下用例：

1. 使用 default/static/private 接口方法将库编译为 DEX（minSdk < 24），并使用保留接口方法的规则。
2. 使用类路径和 -applymapping 上的库编译应用。
3. 合并应用和库。

请注意，这仅适用于 -applymapping，因为 disallow obfuscation 位不会转移到伴生方法，也就是说，第 1 步中生成的伴生类的方法名称会被混淆。

今后，minSdk < 24 将不再支持此用例。解决方法是执行以下操作：

1. 将具有 default/static/private 接口方法的库脱糖为具有 minSdk < 24 的类文件。
2. 使用 R8 和在伴随类上保留接口方法的规则编译脱糖工件。
3. 使用类路径中的库编译应用。
4. 合并应用和脱糖工件。

另一个副作用是，无法再在接口伴生方法中保留匿名类和局部类的内部类和封闭方法属性。

将默认发出的源文件更改为 r8-map-id-<MAP_ID>

此变更自 8.12.0 起在 AGP 中生效。

当需要回溯时（即启用混淆处理或优化时），类的默认发出的源文件属性会从 SourceFile 更改为 r8-map-id-<MAP_ID>。

对于经过混淆处理的堆栈轨迹，新的源文件属性可以提取轨迹还原所需的映射文件的 ID，该 ID 可用于支持在 Logcat 中自动还原堆栈轨迹。

如果使用了自定义源文件属性 (-renamesourcefileattribute)，则此自定义源文件属性仍会优先使用。

在 ProGuard 兼容模式下（当 gradle.properties 包含 android.enableR8.fullMode=false 时），只有在不保留 SourceFile 属性的情况下，发出 r8-map-id-<MAP_ID> 的源文件属性才会生效。如果应用使用 ProGuard 兼容模式，并且希望在堆栈轨迹中包含映射文件 ID，则应移除 -keepattributes SourceFile（或迁移到 R8 完整模式）。

r8-map-id-<MAP_ID> 中使用的映射 ID 是完整映射哈希，而不是之前使用的映射哈希的 7 个字符前缀。

在 L8 脱糖中启用最小化合成名称

D8 生成的合成类的名称通常包含子字符串 $$ExternalSynthetic，该子字符串表示这是 D8 生成的合成类。此外，合成类的名称还会对合成类型（例如 Backport、Lambda）进行编码。这会对生成的 DEX 大小产生负面影响，因为类名称会在字符串池中占用更多空间。

AGP 9.0 会配置 L8（核心库脱糖），以便包含所有 j$ 类的 DEX 文件对合成类使用新的缩短类名格式。新类名称使用数字 ID（例如 $1）。

移除对 -addconfigurationdebugging 的支持

AGP 9.0 移除了对 -addconfigurationdebugging 的支持。现在，如果使用该标志，编译器会报告警告。

移除了对从 D8/R8 生成 L8 规则的支持

此变更仅与直接使用 D8/R8 命令行或 API 的开发者相关。

R8 9.0 移除了对从 D8 和 R8 为 L8 生成 keep 规则的支持。 您应改用 TraceReferences。

更具体地说，方法 D8Command.builder.setDesugaredLibraryKeepRuleConsumer 和 R8Command.Builder.setDesugaredLibraryKeepRuleConsumer 已被移除，并且 D8 和 R8 的命令行选项中已移除对 --desugared-lib-pg-conf-output 的支持。

修复的问题

Android Gradle 插件 9.0.0