使用 Android Gradle 插件升级助理

Android Gradle 插件 (AGP) 升级助理是 Android Studio 中的一个工具,可帮助您升级项目所使用的 AGP 版本。

我们会定期发布与新功能有关的 AGP 更改,以配置 build、供其他 Gradle 插件使用的新 API,并优化项目 build 与 Android Studio 的集成。升级项目使用的 AGP 版本可帮助您利用最新的功能。

AGP 升级助理的用途是什么?

AGP 升级助理将引导您完成升级 AGP 版本所需的更改。以下是升级助理最常见的用例:

  • 语法更改:升级助理会尝试将旧版 AGP 的 build 文件转换为新版 AGP 所需的文件。在开发 AGP 时,我们会更新 build 文件,以支持逐步被替换、废弃或不受支持的接口。

  • AGP 和 Gradle 之间的兼容性要求:升级助理了解 AGP 和 Gradle 之间的兼容性要求,并可帮助您确保使用您的 AGP 版本所需的 Gradle 版本。

  • AGP 与第三方 Gradle 插件之间的兼容性要求:升级助理了解 AGP 与某些第三方 Gradle 插件之间的兼容性要求,并可帮助您确保使用您的 AGP 版本所需的第三方 Gradle 插件版本。

一般来说,升级助理旨在消除部分对 build 文件进行试错性更改的需要,或推测升级后错误消息的含义,并解释有必要进行其建议的更改的原因。

如何使用 AGP 升级助理

如需使用升级助理,请确保您的项目结构符合要求,然后通过 Android Studio 运行它,如下所述。

设置

在运行升级助理之前,请确保您的项目格式正确并且已备份。

使用 Gradle build 文件和网域专用语言构建您的项目

AGP 升级助理在您执行以下操作时最有可能发挥作用:

  • 使用 Gradle build 文件配置 build:升级助理依赖于 Gradle build 文件的静态分析。若要充分利用升级助理,您应该使用这些 build 文件配置 build。请注意,升级助理不支持使用 buildSrc 定义 build 文件中使用的常量和变量的项目。通常,我们不建议使用 buildSrc 构建项目,因为这样做可能会非常低效:对 buildSrc 常量和变量的更改(无论多微小),都会触发重新构建整个项目。
  • 使用声明式 build 网域专用语言:Gradle build 文件完全以 Groovy 和/或 Kotlin 编程语言编写;不过,项目配置表示的声明性越强,升级助理成功找到需要为升级进行调整的所有位置的几率就越大。

即使项目未超出这些限制,升级助理仍可能无法执行彻底的升级。如需有关如何解决或报告 bug 的指导,请参阅问题排查

备份您的项目

在开始使用升级助理之前,建议您确保项目不存在版本控制系统看来未提交的任何更改。如果您未使用版本控制,建议您在此时备份最新一个已知的正常版本。

在升级助理运行且成功构建和测试项目后,您可以将项目的新版本提交到您的版本控制系统。

运行升级助理

如需运行升级助理,请按以下步骤操作:

  1. 从通知提示中启动升级助理,或转到 Tools > AGP Upgrade Assistant... 启动升级助理。随即出现的工具窗口中会显示从项目的当前版本 AGP 升级到此版本 Android Studio 所支持的最新版本 AGP 的默认详细信息。
启动后的 AGP 升级助理工具窗口以及通知提示。
图 1. 启动后的 AGP 升级助理工具窗口以及通知提示。
  1. 查看必需的步骤和建议的步骤。左侧面板中有一个包含复选框的树状图,其中详细列出了升级过程中的各个步骤,并按照以下情况对其进行了分类:对于更新而言是必需步骤还是建议步骤,以及是不是其他步骤的先决条件。选择树状图中的各个项可以在主面板中显示有关每个步骤的更多详细信息。

  2. 运行升级,方法是选择必需或所需的步骤,然后点击 Run selected steps。升级助理会对项目 build 文件进行更改,并尝试将新的项目 build 与 Android Studio 同步。如果您有多个模块,这可能需要一些时间,因为可能需要下载新版插件和库。

  3. 在项目与 Android Studio 成功同步后,构建项目并运行测试套件,以验证升级操作是否未更改任何功能。

  4. 确认项目处于正常状态后,请将项目的新版本提交到您的版本控制系统。

问题排查

如果升级助理提供升级,但升级失败了(通常是因更改 build 文件而导致同步失败),您可以采取一些步骤来帮助隔离和修复错误。

  • 首先,检查导致同步失败的错误。有时,错误有明确的原因,您可以在项目的 build 文件中解决。

  • 如果错误消息不清晰或导致问题的原因不明显,则需要将项目恢复到最初的状态,将升级过程分解为更小的步骤。从版本控制或备份恢复到原始状态,并确保项目(处于原始状态)再次与 Android Studio 同步。然后,您可以使用以下两种升级细分方法进行调查:

    • 升级到不是最新版本的 AGP。如果出现错误的升级是大量版本的升级,则着手查找原因并帮助隔离问题的最佳办法就是,进行一系列较小的升级,以找到造成问题的第一个升级。
    • 在升级过程中,一次只执行一个步骤。找到 AGP 的连续版本之间触发问题的升级后,我们就可以关闭升级过程中的单个步骤。这样,我们就可以尝试一次执行一个步骤,从而找出导致问题的步骤。如果找不到该步骤,就应该查看您所使用的任何其他 Gradle 插件的版本说明,看看是否存在与 Gradle 或 AGP 的兼容性问题;有时,会发布一个新版本来解决使用已废弃或内部 API 的问题。
  • 报告 bug。有时,所有的准备步骤和同步都成功了,而最终的升级步骤仍然失败。在这种情况下,请报告 bug。

即使您自己成功修复了错误,请仍然向 bug 跟踪器报告原始故障,以便开发团队解决该问题。