这是我踩过 AGP/Gradle/Kotlin 版本不适配的坑后整理的笔记——Android Studio 里最常遇到的一类报错就是版本对不上。记得有次升级 AGP 大版本，一编译满屏红，报错信息还看不懂，网上搜一圈，答案全指着"版本兼容表"；对着表把版本调对，编译就好了。后来踩多了发现：报错虽然五花八门，但排查的顺序就那么几条。这篇先把 AGP/Gradle/Kotlin 三者谁管谁讲清楚，再给常用兼容段位和一套排查报错的顺序。
一、AGP 是什么
AGP = Android Gradle Plugin（Android 给 Gradle 的专用插件）。
Gradle 本身是通用构建工具（Java/Kotlin/C++ 项目都能用），但它不知道"Android 项目"长什么样。AGP 就是给 Gradle 装上"Android 专用能力"：
| 层 | 职责 | 例子 |
|---|---|---|
| Gradle | 通用构建引擎：依赖下载、任务执行、打包 | Gradle 9.3.1 |
| AGP | Android 专属：编译 Android 代码、合并 Manifest、打包 APK/AAB、管理 buildType/flavor | AGP 9.1.0 |
| Kotlin (KGP) | Kotlin 编译器插件：.kt 编译成字节码、DSL 脚本解析 | Kotlin 2.4.x |
关系：Gradle 是引擎（跑一切），AGP 和 KGP 是装在引擎上的插件——插件版本必须和引擎版本匹配，这就是"版本适配"问题的来源。
二、版本写在哪（三处关键位置）
# ① Gradle 版本：gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.1-bin.zip
# ② AGP + Kotlin 版本：gradle/libs.versions.toml（Version Catalog 版本目录）
[versions]
androidGradlePlugin = "9.1.0" # ← AGP 版本
kotlin = "2.4.10" # ← Kotlin 版本
# ③ 项目里引用：根 build.gradle.kts / settings 的 plugins 块
plugins {
id("com.android.application") version "9.1.0" apply false
id("org.jetbrains.kotlin.android") version "2.4.10" apply false
}改版本就改这两处（新版项目用 libs.versions.toml 集中管版本；AS 里 File → Project Structure → Project 也能改）。
三、版本兼容矩阵（官方，背熟常用段）
| AGP | 最低 Gradle | 常见配套 Kotlin | JDK |
|---|---|---|---|
| 9.3 | 9.5.0 | 2.3.x | 17 |
| 9.2 | 9.4.1 | 2.3.x | 17 |
| 9.1 | 9.3.1 | 2.3-2.4.x | 17 |
| 9.0 | 9.1.0 | 2.2.x | 17 |
| 8.13 | 8.13 | 2.3.x | 17 |
| 8.11 | 8.13 | 2.2.x | 17 |
| 8.9 | 8.11.1 | 2.1.x | 17 |
| 8.7 | 8.9 | 2.0.x | 17 |
| 8.2 | 8.2 | 1.9.x | 17 |
| 7.4 | 7.5 | 1.8.x | 11 |
规则：
- Gradle 可以比最低版本高（向上兼容），但不能低于最低要求
- AGP 8.x 起强制 JDK 17；AGP 7.x 用 JDK 11
- Android Studio 的时间窗口策略：每个 AS 版本支持近 3 年内发布的 AGP（如 Panda 4 | 2025.3.4 支持 AGP 7.1-9.2）——AS 太老、AGP 太新也会报错
四、版本不适配的典型报错（对号入座）
| 报错关键字 | 含义 | 处理 |
|---|---|---|
AGP requires Gradle X.X or higher. Current version is Y.Y | Gradle 太旧 | 升 gradle-wrapper.properties 的 Gradle 版本 |
Failed to apply plugin 'com.android.application' | AGP 与 Gradle/环境不匹配 | 对照矩阵调 AGP 或 Gradle |
Could not find org.jetbrains.kotlin.android:X.X.X | KGP 版本不存在/与 AGP 不匹配 | 换官方推荐的 Kotlin 版本 |
Unsupported class file major version 61 | JDK 版本太高/太低 | AGP 8.x 用 JDK 17 |
Minimum supported Gradle version is X.X | Gradle 太低 | 升 Gradle |
识别口诀：报错里出现版本号 + "requires/supported/find" → 十有八九是版本适配问题 → 查矩阵。
五、怎么改（升级/降级三步走）
# 1. 改 Gradle：gradle-wrapper.properties
distributionUrl=...gradle-9.3.1-bin.zip
# 2. 改 AGP/Kotlin：根 build.gradle.kts
plugins { id("com.android.application") version "9.1.0" ... }
# 3. 重新同步（AS 里点 Sync，或命令行）
./gradlew --version # 确认 Gradle 生效
./gradlew clean assembleDebug # 验证构建升级顺序建议：先升 Gradle → 再升 AGP → 最后 Kotlin（逐层验证，报错好定位）。
六、实战案例（模板项目 AGP 9.1）
环境实测（AndroidAppTemplate 模板项目）：
$ ./gradlew --version
Gradle 9.3.1 ← 引擎版本（gradle-wrapper.properties）
Kotlin: 2.2.21 ← Gradle 内嵌 Kotlin（非项目 KGP）
$ grep -E "androidGradlePlugin|^kotlin" gradle/libs.versions.toml
androidGradlePlugin = "9.1.0" ← AGP 版本（Version Catalog 版本目录）
kotlin = "2.4.10" ← 项目 Kotlin 版本对照矩阵：AGP 9.1 → 最低 Gradle 9.3.1，当前 9.3.1 —— 恰好踩线 ✅。
⚠️ 版本对上了也不代表没坑：AGP 9.x 的 R8 行为变激进（接口收缩策略变了），导致 Retrofit 接口被打 release 包时被删、启动闪退——这就是"版本升级带来隐性行为变化"的典型。排查方法见《Android R8 混淆：Retrofit 接口被收缩导致崩溃》。
小结
- 三件套：Gradle（引擎）+ AGP（Android 插件）+ KGP（Kotlin 插件），版本互相约束
- 报错套路：看到版本号 + requires/supported → 查 AGP↔Gradle 矩阵（AGP 9.x 配 Gradle 9.x，AGP 8.x 配 8.x+）
- 改动位置：gradle-wrapper.properties（Gradle）+ 根 build.gradle.kts（AGP/Kotlin），升完重新 Sync
- 警惕升级副作用：版本对齐只是"能构建"，AGP 大版本升级可能有行为变化（如 9.x 的 R8），升级后要回归测试
验证说明：AGP↔Gradle 兼容矩阵为官方文档数据（developer.android.com，2026-06 更新，静态核对）；模板项目
./gradlew --version+libs.versions.toml本地实测：Gradle 9.3.1 + AGP 9.1.0 + Kotlin 2.4.10（与矩阵 AGP 9.1 → Gradle ≥9.3.1 吻合）✅。