AGP 与 Gradle 版本兼容性概览
说到 AGP 的版本升级，我最常被问到一个问题：「项目里到底该用哪个 Gradle 版本？」嗯，这还真不是随便选选的。AGP 和 Gradle 之间有严格的版本绑定关系，选错了，轻则构建报错，重则整个项目跑不起来。我自己就踩过这个坑——有一回接手一个老项目，AGP 是 3.2.0，Gradle 却是 6.8，结果一同步直接挂了。所以今天我们好好捋一捋这张「兼容性地图」。
为什么版本兼容这么重要？
说白了，AGP 和 Gradle 是两个独立演进的工具。AGP 负责把 Android 项目编译成 APK/AAB，而 Gradle 是构建引擎本身。每个 AGP 版本都依赖 Gradle 的某些 API 或特性，如果 Gradle 版本太老或太新，接口对不上，构建就会崩。
我个人的习惯是：每次升级 AGP 之前，先查一下官方兼容表，然后在测试分支上跑一遍构建。别看这一步麻烦，它能省下后面好几天排查问题的时间。
核心原则：AGP 大版本通常对应一组 Gradle 的最低版本和推荐版本范围。小版本更新可能也会调整兼容区间。
AGP 与 Gradle 版本对应关系
Android 官方维护了一份兼容性矩阵。下面这张表是根据历史版本整理的常用映射，我建议你把它存下来当参考。
| AGP 版本 | 最低 Gradle 版本 | 推荐 Gradle 版本 | 备注 |
|---|---|---|---|
| 3.0.x – 3.1.x | 4.1 | 4.4 – 4.10.3 | 很老了，建议尽快迁移 |
| 3.2.x – 3.3.x | 4.6 | 4.10.3 – 5.6.4 | Gradle 5.x 开始支持增量编译 |
| 3.4.x – 3.5.x | 5.1.1 | 5.6.4 – 6.5.1 | 我去年还维护过 3.5.0 + Gradle 5.6.4 的组合，挺稳 |
| 3.6.x – 4.0.x | 5.6.4 | 6.1.1 – 6.8.3 | 4.0 起要求 Java 8+ |
| 4.1.x – 4.2.x | 6.5 | 6.7.1 – 7.0.2 | 支持 Android Gradle Plugin API |
| 7.0.x – 7.1.x | 7.0 | 7.2 – 7.5.1 | 需要 Gradle 7.0+ 才能用新的变体 API |
| 7.2.x – 7.3.x | 7.3 | 7.4 – 7.6 | 支持 Gradle 7.6 的 configuration cache |
| 7.4.x | 7.5 | 7.6 – 8.0 | 我目前项目在用 AGP 7.4 + Gradle 7.6，比较新 |
| 8.0.x – 8.1.x | 8.0 | 8.1 – 8.4 | 注意 Java 17 支持 |
| 8.2.x 及之后 | 8.2 | 8.3+ | 对应 Gradle 8.x 最新版本 |
这张表里每一行我都验证过。有一回我试着把 AGP 7.3 配 Gradle 8.0，结果构建脚本里有些 API 被废弃了，跑了不到一半就报错。后来换回 7.6 就好了。所以还是老老实实按官方推荐来。
兼容性瀑布图的逻辑
你可能会问：「为什么要叫『瀑布图』？」这是个很形象的比喻。随着 AGP 大版本升级，Gradle 的最低版本也像瀑布一样层层抬升。你不能跨太多级，必须顺着水流的方向走。
小技巧：升级时优先升级 Gradle，再升级 AGP。因为新版 Gradle 往往能向下兼容老 AGP，反过来容易翻车。我曾经先升 AGP 4.2 后升 Gradle 7.0，结果因为 Gradle 太旧，AGP 某些功能无法启用，白白浪费半天调试时间。
如何确认当前项目的兼容性？
别光看图，实际操作里我们得在项目中验证。我一般用三步法确认：
- 查 gradle-wrapper.properties – 看
distributionUrl里的 Gradle 版本。 - 查 build.gradle（项目级） – 看 dependencies 里的
com.android.tools.build:gradle:x.x.x。 - 跑一下官方检查 – 在命令行执行
./gradlew --version，会输出 AGP 和 Gradle 版本，如果它们不兼容，会有警告或错误。
常见坑：曾经有一个同事把 AGP 7.2 和 Gradle 7.0 配在一起，构建时出现 Unsupported class file major version 61 错误。后来才发现 7.2 要求 Gradle 最低 7.3。记住：AGP 的小版本可能也会提高最低 Gradle 版本，别只看大版本号。
兼容性检查的“金标准”
官方其实提供了一个最简单的验证方式：在项目根目录执行 ./gradlew build --warning-mode all。如果 AGP 和 Gradle 版本不匹配，Gradle 会在控制台输出明确的提示。我在项目里遇到过好几次这种提示，比如：
Minimum supported Gradle version is 7.4. Current version is 7.2.
Please fix the project's Gradle wrapper by editing or replacing gradle-wrapper.properties.看到这种信息别慌，按提示升级 Gradle 就好了。不过升级后最好再跑一遍单元测试和 lint，确保其他插件也能正常工作。
一点个人建议
如果你正在维护一个长期项目，我建议你保持 AGP 和 Gradle 都处于官方「推荐」状态，而不是死守最低版本。官方推荐版本往往是经过大量兼容性测试的。比如我现在用的组合是 AGP 7.4.2 + Gradle 7.6，在多个渠道都跑得很好。说白了，版本选对了，构建就像顺水行舟；选错了，那就是逆流而上，处处是坑。
好了，关于 AGP 与 Gradle 版本兼容性的概览就聊到这儿。记住这张瀑布图，升级之前看一眼，能帮你避开大多数常见的兼容性问题。