Android Gradle 插件 API 更新

本页面跟踪 Android Gradle 插件 (AGP) API 的弃用和移除情况，并提供相应更新代码的信息。

API 弃用和移除跟踪器

下表总结了 AGP API 在不同 AGP 版本中的弃用和移除时间。

AGP 8.8

以下是 AGP 8.8 的重要 API 更新。

资源配置已弃用

资源配置已于 AGP 8.8 版本中弃用。这是因为 AGP 不再支持不同的资源密度，并且 Google Play 管理中心现在要求应用以 App Bundle 形式发布。对于语言配置，您可以使用 localeFilters DSL 指定您的应用支持的区域设置，以将区域设置配置映射到相应的资源。

AGP 8.0

以下是 AGP 8.0 的重要 API 更新。

Transform API 已移除

从 AGP 8.0 开始，Transform API 已移除。这意味着 com.android.build.api.transform 包中的所有类均已移除。

移除 Transform API 旨在提升构建性能。使用 Transform API 的项目会强制 AGP 使用次优的构建流程，这可能导致构建时间大幅回退。此外，Transform API 也很难与其他 Gradle 功能结合使用；替代 API 旨在更轻松地扩展 AGP，而不会引入性能或构建正确性问题。

替代 API

Transform API 没有单一的替代方案——每个用例都有新的、有针对性的 API。所有替代 API 都在 androidComponents {} 代码块中。这些 API 都已在 AGP 7.2 中可用。

支持转换字节码

要转换字节码，请使用 Instrumentation API。对于库，您可以仅为本地项目类注册插桩；对于应用和测试，您可以选择仅为本地类或所有类（包括本地和远程依赖项）注册插桩。要使用此 API，插桩会在每个类上独立运行，对类路径中的其他类的访问受限（有关详细信息，请参阅 createClassVisitor()）。此限制可提高完整构建和增量构建的性能，并使 API 接口保持简单。每个库都在准备就绪后立即并行插桩，而不是在所有编译完成后。此外，单个类的更改意味着在增量构建中只需重新插桩受影响的类。有关如何使用 Instrumentation API 的示例，请参阅“使用 ASM 转换类”AGP 秘籍。

支持将生成的类添加到您的应用

要将其他生成的类添加到应用中，请将 Artifacts API 与 MultipleArtifact.ALL_CLASSES_DIRS 一起使用。具体来说，使用

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

将 MultipleArtifact.ALL_CLASSES_DIRS 添加到项目类以附加其他生成的目录。Artifacts API 将自动为您的自定义任务选择一个唯一的输出位置。有关如何使用此 API 的示例，请参阅 addToAllClasses 秘籍。

支持基于整个程序分析的转换

要实现基于整个程序分析的转换，所有类可以在单个任务中一起转换。应谨慎使用此方法，因为它比使用 Instrumentation API 的构建性能成本高得多。如果您的插件使用此 API，建议按构建类型选择启用转换，以便应用开发者可以为开发构建禁用它。

为了注册一个同时转换所有类的任务，Android Gradle 插件 7.4 引入了 Artifacts.forScope API。要转换当前项目中的所有类，请使用 Artifacts.forScope.PROJECT。要转换当前项目、导入项目和所有外部依赖项中的所有类，请使用 Artifacts.forScope.ALL。以下代码演示了如何使用 Artifacts.forScope.ALL 注册一个同时转换所有类的任务

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

有关如何使用此 API 的示例，请参阅 modifyProjectClasses 秘籍；有关如何为 Android 构建类型注册自定义扩展的示例，请参阅 customizeAgpDsl 秘籍。

如果您的用例未被任何 AndroidComponents API 涵盖，请提交错误。

许多常用插件已迁移到使用这些新 API，包括 Firebase 性能监控插件（1.4.1 版兼容 AGP 8.0）和 Hilt Gradle 插件（2.40.1 版兼容 AGP 8.0）。AGP 升级助手还将根据需要帮助项目开发者升级常用插件。

如果您通过第三方插件使用 Transform API，请告知作者他们的插件需要更新以与 AGP 8.0 的新 API 兼容。

AGP 7.2

以下是 AGP 7.2 的重要 API 更新。

RenderScript 已弃用

从 AGP 7.2 开始，RenderScript API 已弃用。它们将继续运行，但会发出警告，并将在 AGP 的未来版本中完全移除。有关如何从 RenderScript 迁移的指南，请参阅从 RenderScript 迁移。

Component.transformClassesWith 和 Component.setAsmFramesComputationMode 已弃用

从 AGP 7.2 开始，类字节码插桩 API Component.transformClassesWith 和 Component.setAsmFramesComputationMode 已弃用。它们已移至新的 Component.instrumentation 代码块，其中包含所有与配置插桩过程相关的 API。要继续使用这些插桩功能，请改用新代码块中的相应 API，如下面的代码片段所示

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }