使用 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 的使用。

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