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 表达。但是，项目配置的表达越是声明性的，升级助手成功找到所有需要调整的地方的可能性就越大。
即使项目符合这些限制，升级助手仍可能无法进行干净的升级。有关如何解决或报告错误的指导，请参阅问题排查。
备份您的项目
在使用升级助手之前，我们建议您的项目没有任何未提交的更改（如您的版本控制系统所示）。如果您没有使用版本控制，请在此处使用最后一个已知良好版本的备份。
升级助手运行成功且项目成功构建并测试后，您可以将项目的新版本提交到您的版本控制系统。
运行升级助手
要运行升级助手，请按照以下步骤操作：
要启动升级助手，请导航到工具 > AGP 升级助手，或点击通知提示（如图 1 所示）。
出现的工具窗口会显示默认升级的详细信息，包括项目的当前 AGP 版本和此版 Android Studio 支持的最新版本。
图 1. 启动通知提示时显示的 AGP 升级助手工具窗口。 检查所需和建议的步骤。
在左侧面板中，带有复选框的树详细说明了升级中的各个步骤，按其是否需要或建议更新以及它们是否是其他步骤的先决条件进行分类。选择树中的单个项目以在主面板中显示每个步骤的更多详细信息。
要运行升级，请选择所需和期望的步骤，然后点击运行选定的步骤。
升级助手会更改项目构建文件，并尝试将新的项目构建与 Android Studio 同步。如果您有大量模块，这可能需要一段时间，因为可能需要下载新版本的插件和库。
查看升级后报告。此报告描述了已完成的步骤，以及升级是成功还是不成功。如果升级后构建或测试项目时出现问题，它还包括一个操作，用于撤消升级助手所做的更改。
项目成功与 Android Studio 同步后，构建项目并运行测试套件以验证升级操作未更改任何功能。
验证您的项目处于良好状态后，将项目的新版本提交到您的版本控制系统。
问题排查
如果升级助手建议升级但升级失败，这通常是由于更改了构建文件，导致同步失败。请按照以下步骤帮助隔离和解决错误：
首先，检查导致同步失败的错误。有时，错误有明确的原因，您可以在项目的构建文件中解决。
如果错误消息不明确，或者导致问题的原因不明显，则将项目恢复到原始状态，以便将升级分解为更小的步骤。从版本控制或备份中恢复原始状态，并确保项目处于原始状态并与 Android Studio 同步。
通过以下两种升级分解来调查错误：
升级到不是最新版本的 AGP。如果出现问题的升级涉及到大量版本，隔离问题的最佳方法是进行一系列较小的版本到版本升级，以找到触发问题的第一次升级。
在升级中，一次执行一个步骤。一旦您确定了触发问题的升级，就可以关闭升级中的单个步骤。如果可能，请尝试一次执行一个步骤，以找出哪个步骤导致了错误。如果您找不到负责的步骤，请检查您正在使用的任何其他 Gradle 插件的发布说明，以了解与 Gradle 或 AGP 的兼容性问题。有时，新版本会解决弃用或内部 API 的使用。
报告 bug。有时，所有准备步骤和同步都成功了，但最后的升级步骤仍然失败。在这种情况下，请报告 bug。即使您成功地自行修复了错误，也请向 bug 跟踪器报告原始故障，以便开发团队能够解决问题。