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 完成了向完全延迟加载、与配置缓存兼容的构建模型的过渡。此版本是多年来努力用更安全、性能更高的架构取代旧版非延迟加载 API 的成果。

为什么要使用延迟加载构建模型？

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

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

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

核心架构差异

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

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

移除和替换的内容

旧版 DSL 和旧版 Variant API 中使用的所有旧版接口和类均已删除。如需准备构建脚本和自定义插件，请从以下生命周期结束的 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` 中移除这些标志gradle.properties；现代 DSL 和内置 Kotlin 将 严格执行。
旧版 Variant API 扩展：
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 替换为 androidComponents.onVariants()。
变体过滤（variantFilter 块） 使用 变体选择器 替换为 androidComponents.beforeVariants()。
SDK 和 NDK 组件：
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 使用 SDK 组件访问 androidComponents.sdkComponents.
测试环境：
  • deviceProvider
  • testServer
 将自定义测试设备注册迁移到 Gradle 管理的设备。
已过时的注册 API：
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 已删除，无直接替换项。
Transform API 使用 Artifacts API 和 AsmClassVisitorFactory. 替换转换。

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

迁移步骤

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

  1. 运行 AGP 升级助理： 在直接升级到 10.0 之前，请在 Android Studio 中运行 官方 AGP 升级助理（Tools > AGP Upgrade Assistant）。它会自动执行一些 常见的 DSL 和构建脚本迁移，并有助于保留现有的构建 行为。
  2. 在 Android Studio 中使用代理模式技能： 利用 AI 升级 技能（例如 Android 技能库中提供的 AGP 升级技能），在 Android Studio 中自动执行并简化复杂构建逻辑和 DSL 的迁移。
  3. 先修复 AGP 9.x 中的废弃警告： 将项目升级到最新的 AGP 9.x 版本，并解决所有现有的废弃警告。如果您的项目在没有警告且不依赖于 android.newDsl=false 或 android.builtInKotlin=false 的情况下使用 9.x，则迁移到 10.0 将会非常顺利。
  4. 审核第三方 Gradle 插件： 确保第三方插件已升级到与 AGP 10.0 兼容的版本。仍依赖于旧版扩展类型的插件会导致构建失败，例如 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
        }
    }
}

之后：现代 Variant 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 发布即可开始测试其构建行为并验证兼容性。在任何 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，您可以验证自定义构建逻辑和第三方插件是否与 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

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

android {
    enableKotlin = false
}

反馈和 bug 报告工作流

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

  1. 检查现有条目： 首先，检查 AGP 10.0 Variant API 全局 跟踪 bug，看看您的迁移障碍是否 已知，然后为该问题添加 +1。
  2. 报告缺失的 API： 如果您的用例是独一无二的，请使用我们的特定 Variant API 模板提交新的功能 请求，以便 我们进行调查和协助。

（暂定）对私有内部 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 类，但不建议您使用它们，因为它们随时都有可能发生重大变化。