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 插件版本。
通常，升级助力可以使您在 AGP 升级后更轻松地更新 build 文件和理解相关错误消息。升级助理还会解释建议的更改的必要性。
如何使用 AGP 升级助理
如需使用升级助理，请确保您的项目结构符合该工具的要求，然后通过 Android Studio 运行该工具，如
运行升级助理
中所述。
在运行升级助理之前，请确保您的项目格式正确并且已备份。为确保 AGP 升级助理设置正确，请阅读以下部分。
使用 Gradle build 文件和网域专用语言构建您的项目
若要充分利用 AGP 升级助理，请执行以下操作：
使用 Gradle build 文件配置 build
：升级助理依赖于 Gradle build 文件的静态分析。若要充分利用升级助理，请使用这些 build 文件配置 build。
使用声明式 build 领域专用语言
：Gradle build 文件以 Groovy 或 Kotlin 编写。不过，项目配置表示的声明性越强，升级助理成功找到需要为升级进行调整的所有位置的几率就越大。
即使项目符合这些限制，升级助理仍可能无法执行彻底的升级。如需有关如何解决或报告 bug 的指导，请参阅
排查错误
。
备份您的项目
在使用升级助理之前，建议您确保项目不存在版本控制系统看来未提交的任何更改。如果您未使用版本控制，此时可以使用最新一个已知的正常版本的备份。
在升级助理运行且成功构建和测试项目后，您可以将项目的新版本提交到您的版本控制系统。
运行升级助理
如需运行升级助理，请按以下步骤操作：
如需启动升级助理，请依次进入
Tools > AGP Upgrade Assistant
或点击通知提示，如图 1 所示。
随即出现的工具窗口中会显示默认升级的详细信息，其中包括项目的当前版本 AGP 以及此版本 Android Studio 所支持的最新版本。
图 1.
启动后的 AGP 升级助理工具窗口以及通知提示。
查看必需的步骤和建议的步骤。
在左侧面板中，带有复选框的树状图详细说明了升级过程涉及的各个步骤，这些步骤按必须更新还是建议更新，以及它们是否是执行其他步骤的先决条件进行分类。选择树状图中的各个项可以在主面板中显示有关每个步骤的更多详细信息。
如需运行升级，请选择必需或所需的步骤，然后点击
Run selected steps
。
升级助理会更改项目 build 文件，并尝试将新的项目 build 与 Android Studio 同步。如果您有多个模块，这可能需要一些时间，因为可能需要下载新版插件和库。
查看升级后报告。此报告介绍了已完成的步骤以及升级是成功还是失败。它还包含一项操作，如果在升级后构建或测试项目时遇到问题，用来还原由升级助理所做的更改。
在项目与 Android Studio 成功同步后，构建项目并运行测试套件，以验证升级操作是否未更改任何功能。
确认项目处于正常状态后，请将项目的新版本提交到您的版本控制系统。
如果升级助理建议升级，但升级失败了，这通常是因更改 build 文件而导致同步失败。请按照以下步骤帮助隔离和修正错误：
首先，检查导致同步失败的错误。有时，错误有明确的原因，您可以在项目的 build 文件中解决。
如果错误消息不清晰或导致问题的原因不明显，请将项目恢复到原始状态，以便将升级过程细分为更小的步骤。通过版本控制或备份恢复原始状态，并确保项目处于原始状态并与 Android Studio 同步。
请按照以下两种升级细分方法来调查错误：
升级到不是最新版本的其他版本的 AGP。
如果出现错误的升级是大量版本的升级，则隔离问题的最佳办法就是，进行一系列较小的升级，以找到第一个触发问题的升级。
在升级过程中，一次只执行一个步骤。
确定触发问题的升级后，即可关闭升级过程中的单个步骤。如果可能的话，请尝试一次执行一个步骤，从这些步骤中找出导致错误的具体步骤。如果您找不到导致错误的具体步骤，请查看您使用的任何其他 Gradle 插件的版本说明，看看是否存在与 Gradle 或 AGP 的兼容性问题。有时，新版本会解决使用已废弃或内部 API 带来的问题。
报告错误
。
有时，所有的准备步骤和同步都成功了，但最终的升级步骤仍然失败。在这种情况下，请报告 bug。即使您成功自行修正了错误，也请向 bug 跟踪器
报告原始故障
，以便开发团队解决该问题。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-07-27。"],[],[],null,[]]
