Android Gradle 插件 DSL/API 迁移时间表

Android Gradle 插件 (AGP) 是受支持的 Android 应用构建系统，支持编译多种不同类型的源代码，以及将其链接到可在实体 Android 设备或模拟器上运行的应用中。

以下部分介绍了计划的 AGP DSL 和 API 的演变。随着新版 API 在稳定版本中推出，旧版 API 将标记为已废弃。这些废弃的 API 在下一个稳定版本中将不再可用。以下部分介绍了每个主要 AGP 版本中即将发生的变更。

有关 AGP API 废弃或移除的更详尽日志，请参阅 AGP API 更新。

AGP 10.0（2026 年底）

Android Gradle 插件 10.0 API 变更和现代化

AGP 10.0 完成了向完全延迟、与配置缓存兼容的 build 模型过渡。此版本是多年来努力的成果，旨在用更安全、性能更高的架构来替换旧版非延迟 API。

为什么采用延迟构建模型？

在旧版非延迟构建模型中，Gradle 会在每次同步或构建调用期间，主动评估对象、查询变体数据并配置所有项目模块中的任务。这种急切评估会在未运行的变体和任务上浪费 CPU 时间和内存，并导致复杂 build 脚本中的评估顺序冲突。

通过使用延迟提供程序 (Provider<T>) 和现代 Variant API (androidComponents {}) 过渡到完全延迟的 build 模型，系统仅在有效 build 执行图表需要时才按需延迟计算属性和任务连接。

此版本中移除的旧版 API 从根本上与这种现代架构不兼容。移除这些过时的 API 后，AGP 便可完全支持 Gradle 配置缓存和项目隔离，从而大幅提升 Android Studio 中的 build 速度和同步时间。

核心架构差异

旧版 BaseVariant API (applicationVariants.all {}) 是急切的，并且以任务为中心。它在配置阶段为开发者提供了对 Gradle 任务和内部配置的直接访问权限，这从根本上破坏了现代 Gradle 性能功能。

新的 Variant API (androidComponents {}) 是延迟加载的，并且以制品为中心。它广泛使用 Gradle 的 Property API，并完全移除了对 Task 和 TaskProvider 的所有引用，要求您以清晰的方式与输入和输出 (Variant.artifacts) 进行交互，而不是与底层任务本身进行交互。

移除和替换的内容

旧版 DSL 和旧版 Variant API 中使用的所有旧版接口和类均已删除。如需准备 build 脚本和自定义插件，请迁移掉以下已弃用的 API 和标志：

已移除的 API 或功能 需要更换或采取行动
直接访问任务：
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API：无需提取任务来更改其行为，而是使用 variant.artifacts 来附加、修改或替换在任务之间传递的实际文件（制品）。
急切的来源注册：
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 Sources API：使用 variant.sources.java.addGeneratedSourceDirectory(...) 连接自定义任务的输出目录。
类路径 / 配置访问权限：
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API：如需修改或检查字节码（类路径访问的最常见使用情形），请使用 variant.instrumentation.transformClassesWith(...)（使用 AsmClassVisitorFactory）。
急切属性突变：
  • buildConfigField()
  • resValue()
 延迟 `MapProperty` 实例：使用 variant.buildConfigFields.put(...) 和 variant.manifestPlaceholders.put(...)。
选择退出标志：
  • android.newDsl
  • android.builtInKotlin
 没有直接替代项。从 gradle.properties 中移除了这些标志；严格强制执行现代 DSL 和内置 Kotlin。
旧版 Variant API 扩展程序：
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 替换为 androidComponents.onVariants()。
变体过滤（variantFilter 个块） 使用变体选择器替换为 androidComponents.beforeVariants()。
SDK 和 NDK 组件：
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 使用 androidComponents.sdkComponents 访问 SDK 组件。
测试环境：
  • deviceProvider
  • testServer
 将自定义测试设备注册迁移到 Gradle 管理的设备。
过时的注册 API：
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 已删除，但未直接替换。
Transform API 使用 Artifacts API 和 AsmClassVisitorFactory 替换了转换。

如需访问所有替代 DSL 和 Variant API (androidComponents {}) 接口及类，请在开发自定义 Gradle 插件或 build 逻辑时始终使用 gradle-api 工件。

迁移步骤

为确保您顺利且可预测地升级到 AGP 10.0，请遵循以下迁移实践：

  1. 运行 AGP 升级助理：在直接升级到 10.0 之前，请在 Android Studio (Tools > AGP Upgrade Assistant) 中运行官方 AGP 升级助理。该助理可自动执行多项常见的 DSL 和 build 脚本迁移，并有助于保留现有的 build 行为。
  2. 在 Android Studio 中使用智能体模式技能：利用 AI 升级技能（例如 Android 技能库中提供的 AGP 升级技能）自动执行并简化在 Android Studio 中迁移复杂 build 逻辑和 DSL 的过程。
  3. 先修正 AGP 9.x 中的弃用警告：将项目升级到最新的 AGP 9.x 版本，并解决所有现有的弃用警告。如果您的项目在不依赖 android.newDsl=false 或 android.builtInKotlin=false 的情况下正常运行且没有 9.x 警告，那么迁移到 10.0 将会非常顺利。
  4. 审核第三方 Gradle 插件：确保第三方插件已升级到与 AGP 10.0 兼容的版本。仍依赖于旧版扩展类型的插件会导致 build 失败，例如 ClassCastException: ... cannot be cast to class BaseExtension。
  5. 使用官方迁移方案：如需查看复杂的实际迁移示例和并排比较，请参阅官方 gradle-recipes GitHub 代码库。

以下是迁移前后的对比，展示了如何从急切查询旧版变体迁移到使用 androidComponents {} 延迟配置变体：

之前：旧版 Variant API（已在 AGP 10.0 中移除）

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

之后：现代变体 API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

如何在 AGP 9.x 中测试 AGP 10.0 行为

您无需等待 AGP 10.0 发布，即可开始测试其 build 行为并验证兼容性。在任何 AGP 9.x 版本上运行时，您都可以通过验证 gradle.properties 是否停用任何选择退出并设置以下严格的行为标志，来明确强制执行 AGP 10.0 行为：

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

通过强制执行 android.newDsl=true 和 android.builtInKotlin=true，您可以验证自定义 build 逻辑和第三方插件是否完全符合 AGP 10.0 的严格 API 要求。

在迁移期间选择性退出子项目

如果您想在整个项目中全局启用 android.newDsl=true 以测试新版行为，但需要更多时间来迁移特定子项目，则可以从 AGP 9.4.0-alpha04 开始选择性地停用各个模块。将 android.newDsl.optOut 添加到 gradle.properties，指定项目路径：

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

按模块选择性停用内置 Kotlin

如果您想在整个项目 (android.builtInKotlin=true) 中全局启用内置 Kotlin，但需要更多时间将特定子项目从 kotlin-android 迁移出来（或针对没有 Kotlin 代码的模块），请在 DSL 级别而非项目级别配置这些模块。在模块的 build 文件中设置 enableKotlin = false：

android {
    enableKotlin = false
}

反馈和 bug 报告工作流程

我们希望确保新的 Variant API 支持您所需的用例。如果您在从旧版 API 迁移的过程中遇到阻碍，新版 Variant API 无法满足您的使用情形，请按以下步骤提供反馈：

  1. 检查现有问题：首先，请查看 AGP 10.0 变体 API 全局跟踪 bug，了解您的迁移阻碍因素是否已是已知问题，如果是，请为该问题添加 +1。
  2. 报告缺失的 API：如果您的使用情形比较特殊，请使用我们特定的 AGP 10.0 模板提交新的功能请求，以便我们进行调查并提供帮助。

（暂定）对私有内部 AGP 类的访问权限已移除

对 gradle 制品的依赖项现在会隐藏所有内部类，并仅针对 gradle-api 制品中的可用接口和类提供编译权限。这会影响插件编译。

您无法手动添加依赖项来获取对内部类的访问权限。

AGP 9.0（2026 年 1 月）

新版 Variant API 已稳定，旧版 API 已废弃

在 4.1 和 4.2 中培育的 Variant API 已稳定，位于 gradle-api 工件中。旧版 Variant API 中使用的旧版接口和类现已废弃，需要明确选择启用才能使用。

新版 DSL 接口已稳定，旧版 DSL 接口已废弃

在 4.1、4.2 和 7.0 中培育的 DSL 接口现已稳定，位于 gradle-api 制品中。DSL 中使用的旧版接口和类现已废弃，需要明确选择启用才能使用。

仍然可以访问私有内部 AGP 类

在编译 build 文件和插件时，仍可访问位于其他工件的私有内部 AGP 类，但我们不建议您使用它们，因为它们随时都有可能发生重大变化。