3. AGP 与 Android Studio 版本对应关系
做 Android 构建的人，应该都遇到过版本不匹配的坑。
说白了一句话：AGP 和 Android Studio 不是各自独立的，它们之间有固定的“配对表”。
我自己的开发经历里，至少有三四次因为升级 IDE 忘了同步 AGP 版本，导致跑起来莫名其妙报错。
这一章我就帮你把这些对应关系彻底捋清楚。为啥要搞明白？
因为只要版本对不上，轻则 lint 乱报，重则整个项目打不开。你想想看，排查这类问题往往最浪费时间。
3.1 官方兼容性矩阵
官方文档其实有张表，但信息分散。我把它整合成一个更实用的对照表——按时间线排列，包含 Android Studio 版本、对应的 AGP 版本、推荐的最低 Gradle 版本。这三个因素必须一起看。
注意：高于某个 AGP 版本的 Studio 通常能向下兼容，但反过来不行。
| Android Studio 版本 | 对应 AGP 版本（推荐） | 最低 Gradle 版本 | 发布日期（大致） |
|---|---|---|---|
| 3.0.x | 3.0.0 - 3.0.1 | 4.1 | 2017 年 Q4 |
| 3.1.x | 3.1.0 - 3.1.4 | 4.4 | 2018 年 Q1 |
| 3.2.x | 3.2.0 - 3.2.1 | 4.6 | 2018 年 Q3 |
| 3.3.x | 3.3.0 - 3.3.3 | 4.10.1 | 2019 年 Q1 |
| 3.4.x | 3.4.0 - 3.4.3 | 5.1.1 | 2019 年 Q2 |
| 3.5.x | 3.5.0 - 3.5.4 | 5.6.4 | 2019 年 Q3 |
| 3.6.x | 3.6.0 - 3.6.4 | 5.6.4+ | 2020 年 Q1 |
| 4.0.x | 4.0.0 - 4.0.1 | 6.1.1 | 2020 年 Q2 |
| 4.1.x | 4.1.0 - 4.1.3 | 6.5+ | 2020 年 Q4 |
| 4.2.x | 4.2.0 - 4.2.2 | 6.7.1 | 2021 年 Q2 |
| Chipmunk (2021.2.1+) | 7.0.x - 7.1.x | 7.0+ | 2022 年 Q2 |
| Dolphin (2021.3.1) | 7.2.x | 7.3.3 | 2022 年 Q3 |
| Electric Eel (2022.1.1) | 8.0.x | 8.0 | 2023 年 Q1 |
| Flamingo (2022.2.1) | 8.1.x | 8.1 | 2023 年 Q2 |
| Giraffe (2022.3.1) | 8.2.x | 8.2 | 2023 年 Q3 |
| Hedgehog (2023.1.1) | 8.3.x | 8.3 | 2023 年 Q4 |
build.gradle 改对应版本。这样能避免 90% 的构建兼容性崩溃。
3.2 为什么版本必须严格对应？
道理其实很简单：AGP 插件是直接嵌入 Android Studio 内部的。
Android Studio 本身集成了很多构建工具、布局编辑器、资源管家，这些内部组件都依赖特定版本的 AGP API。
举个例子：AS 4.1 用的 Build Analyzer 调用了 AGP 4.1 里新增的某些类。如果你强行用 AGP 4.0，一打开分析窗口就直接闪退。
我记得有一年我在团队里遇到一个奇怪的事：AS 更新到 4.2 后，同事的工程突然找不到 Aapt2 了。查了半天，原来他还在用 AGP 4.0.0。升级到 4.2.0 就立刻好了。
3.3 避坑指南——我曾经踩过的雷
- 别信“最高版本”的诱惑：有些人喜欢把 AGP 和 Gradle 都拉到最新。但我建议：
先让 AS 自动推荐的版本跑起来，再考虑升级。我遇到过一次把 AGP 从 8.2 升到 8.4，结果因为 Gradle 8.4 本身有个 Kotlin DSL 的 bug，折腾了两天。 - 混合项目注意：如果你的项目同时包含 Java 和 Kotlin，还要注意
kotlin-gradle-plugin的版本和 AGP 的兼容性。这个我后面章节会细化，但这里提一句：Kotlin 1.9.0 配 AGP 8.2 是最稳的。 - Flutter / RN 混合工程：如果你用 Flutter 开发再加上原生 Android 代码，记得 Flutter 的嵌入版本也会限制 AGP 的选择。我曾因为 Flutter 2.10 强制要求 AGP 7.0，而 AS 4.2 只能配 AGP 4.2 —— 最后不得不单独保留一个低版本 Studio。
3.4 对应关系可视化：版本瀑布图
下面这张 SVG 图，把时间维度、AS 版本、AGP 版本、Gradle 版本的关系连在一起。你可以直观看到“谁跟谁配对”。
3.5 快速检查方法（命令行）
有时候你拿到一个老项目，不确定当前用的 AGP 版本。我一般直接用 Gradle 的 dependency 命令检查：
./gradlew buildEnvironment | grep -i agp或者直接在 build.gradle 里搜 com.android.tools.build:gradle:。
如果你在大型团队，我建议在项目的 gradle.properties 里统一声明一个 agpVersion 变量，方便升级时一次性修改。
Could not find com.android.tools.build:gradle:7.0.3。排查后才发现，原来有同事手动改了版本号，却忘了更新 Gradle wrapper 和 distributionUrl，导致下载不到对应的 Gradle 版本。现在我们都强制用 gradle-wrapper.properties 里的版本做校验。
3.6 升级策略建议
- 小步快跑：不要一下子跳两个大版本。比如从 AGP 7.2 升到 7.4 风险很小，但从 7.2 直接跳到 8.3 就容易踩坑。
- 先用官方的 “Project Structure → Suggestions”：AS 里会自动推荐兼容的 AGP 和 Gradle 版本。我习惯先点一下 “Apply” 看能不能通过编译。
- 跑一遍全量测试：别信“只改版本没事”。有一次我只是改了 AGP 版本，结果多个功能模块的
transform报错，因为新版本废弃了某些 API。 - 保留一份调试用的低版本 AS：如果你同时维护多个旧项目，建议装一瓶 AS 3.6 或者 4.0 作为“蓝牌工程师”。我电脑里至今还保留着 AS 4.2 的安装包。