使用 Android Gradle 插件升级助手

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

AGP 经常发布与配置构建的新功能、供其他 Gradle 插件使用的新 API 以及项目构建与 Android Studio 集成的改进相关的更改。升级项目使用的 AGP 版本可让您受益于最新功能。

有关升级助手推荐的项目结构的更多信息，请参阅此页面上的 设置。

AGP 升级助手用例

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

  • 语法更改：升级助手尝试将旧版 AGP 的构建文件转换为新版 AGP 所需的构建文件。随着 AGP 的开发，构建文件会更新以支持随着时间的推移而被替换、弃用或不支持的接口。

  • AGP 与 Gradle 之间的兼容性要求：升级助手了解 AGP 与 Gradle 之间的兼容性要求，并有助于确保您使用的是 AGP 版本所需的 Gradle 版本。

  • AGP 与第三方 Gradle 插件之间的兼容性要求：升级助手了解 AGP 与某些第三方 Gradle 插件之间的兼容性要求，并有助于确保您使用的是 AGP 版本所需的第三方 Gradle 插件版本。

一般来说，升级助手使更新构建文件和理解 AGP 升级后的相关错误消息变得更容易。升级助手还会解释为什么需要进行建议的更改。

如何使用 AGP 升级助手

要使用升级助手，请确保您的项目结构适合该工具，然后从 Android Studio 运行它，如 运行升级助手 中所述。

设置您的项目

在运行升级助手之前，请确保您的项目已正确格式化并已备份。要确保 AGP 升级助手已正确设置，请阅读以下部分。

使用 Gradle 构建文件和领域特定语言构建项目

为了充分利用 AGP 升级助手，请执行以下操作

  • 使用 Gradle 构建文件配置构建：升级助手依赖于对 Gradle 构建文件的静态分析。为了充分利用升级助手，请使用这些构建文件配置您的构建。
  • 使用声明式构建领域特定语言：Gradle 构建文件使用 Groovy 或 Kotlin 表达。但是，项目配置表达得越声明式，升级助手成功找到所有需要调整以进行升级的地方的可能性就越大。

即使项目符合这些限制，升级助手仍可能无法执行干净的升级。请参阅疑难解答，了解如何解决或报告错误。

备份您的项目

在使用升级助手之前，我们建议您的项目没有未提交的更改（如您的版本控制系统所示）。如果您没有使用版本控制，请在此处使用最新已知良好版本的备份。

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

运行升级助手

要运行升级助手，请按照以下步骤操作

  1. 要启动升级助手，请导航到工具 > AGP 升级助手或点击通知提示，如图 1 所示。

    出现的工具窗口显示默认升级的详细信息，包括项目的当前 AGP 版本和此 Android Studio 版本支持的最新版本。

    The AGP Upgrade Assistant tool window when launched, and the notification prompt.
    图 1. 通过通知提示启动时的 AGP 升级助手工具窗口。

  2. 检查必需和推荐的步骤。

    在左侧面板中，带有复选框的树详细列出了升级中的各个步骤，并按其是否需要或推荐更新以及它们是否是其他步骤的先决条件进行分类。选择树中的各个项目以在主面板中显示有关每个步骤的更多详细信息。

  3. 要运行升级，请选择必需和所需的步骤，然后点击运行选定的步骤。

    升级助手将更改项目构建文件，并尝试将新的项目构建与 Android Studio 同步。如果您有很多模块，这可能需要一段时间，因为可能需要下载新版本的插件和库。

  4. 查看升级后报告。此报告描述了已完成的步骤以及升级是否成功。如果升级后出现构建或测试项目的问题，它还包含一个操作以恢复升级助手所做的更改。

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

  6. 验证项目处于良好状态后，将新版本的项目提交到您的版本控制系统。

疑难解答

如果升级助手建议升级但升级失败，这通常是由于对构建文件进行更改而导致同步失败的结果。请按照以下步骤帮助隔离和修复错误

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

  • 如果错误消息不清楚，或者不清楚是什么原因导致问题，则将项目恢复到其原始状态以将升级分解成更小的步骤。从版本控制或备份中恢复原始状态，并确保项目处于其原始状态并与 Android Studio 同步。

通过遵循两种升级分解方法来调查错误

  • 升级到不是最新版本的不同 AGP 版本。如果出错的升级是大量版本的升级，隔离问题的最佳方法是从版本到版本进行一系列较小的升级，以找到触发问题的第一次升级。

  • 在升级中，一次执行一个步骤。确定触发问题的升级后，可能可以关闭升级中的各个步骤。如果可能，尝试一次执行每个步骤以查找哪些步骤导致错误。如果您找不到负责的步骤，请检查您正在使用的任何其他 Gradle 插件的发布说明，了解与 Gradle 或 AGP 的兼容性问题。有时，新版本会解决使用已弃用或内部 API 的问题。

  • 报告错误。有时所有准备步骤和同步都成功，但最终升级步骤仍然失败。在这种情况下，请报告错误。即使您成功自行修复了错误，也请将原始故障报告给错误跟踪器，以便开发团队可以解决此问题。