📚 课程目录第1章 AGP版本与Gradle版本不匹配导致的构建失败

1. AGP版本与Gradle版本不匹配导致的构建失败

构建突然挂了。Gradle Sync 转了半天，最后给你一句冷冰冰的红色报错。这种场景，做 Android 开发的兄弟多半都经历过。

我记得刚接手第一个 Android 项目时，打开前辈留下的代码，一同步就蹦出来这么一段：

ERROR: The Android Gradle plugin requires Gradle 8.0 or higher.
Current version is Gradle 7.5.

当时我还纳闷——明明昨天还好好的，怎么今天就不行了？后来一查才发现，AGP 和 Gradle 之间有严格的版本绑定关系。版本对不上，构建就罢工。

1.1 问题现象：你遇到了什么？

版本不匹配的错误，通常出现在这几个环节：

Gradle Sync 阶段：IDE 直接弹窗，告诉你 AGP 要求的 Gradle 版本和当前版本不一致。
编译打包阶段：执行 ./gradlew assembleDebug 时，控制台输出类似 "Minimum supported Gradle version is X.X" 的提示。
引入新依赖后：某些第三方依赖强制要求特定 AGP 版本，间接牵扯到 Gradle 版本。

错误信息其实很直白。但很多人扫一眼就关了，没仔细看版本号。其实它就是直接告诉你——当前 Gradle 版本太老，或者 AGP 版本太新，两边没对上。

1.2 为什么会这样？

AGP 和 Gradle 的关系，说白了就是插件与框架的关系。AGP 作为 Gradle 的一个插件，必须运行在特定版本的 Gradle 之上。Google 每个 AGP 版本发布时，都会指定一个最低 Gradle 版本和一个推荐的 Gradle 版本。

你想想看，Gradle 本身也在快速迭代，新的 API 不断加入，旧的 API 逐渐废弃。AGP 为了利用新特性或修复底层问题，就会逐步提高对 Gradle 版本的要求。如果你锁死了 Gradle 版本，又想用最新的 AGP，那冲突就来了。

举一个很现实的例子：

AGP 8.0 开始要求 Gradle 8.0+，因为 AGP 8.0 内部大量使用了 Gradle 8.0 新增的配置缓存 API。
如果你还在用 Gradle 7.5，那 AGP 8.0 根本跑不起来。

反过来也一样——Gradle 太新而 AGP 太旧，也可能因为 API 不兼容而报错。不过这种情况相对少一些，Gradle 的向后兼容做得还不错。

1.3 版本对应关系一览

Google 官方维护了一张版本兼容表。我把几个常用版本的对应关系整理了一下：

AGP 版本	最低 Gradle 版本	推荐 Gradle 版本
8.2.x	8.2	8.4
8.1.x	8.0	8.2
8.0.x	8.0	8.1
7.4.x	7.5	8.0
7.3.x	7.4	7.5
7.2.x	7.3	7.4
7.1.x	7.2	7.3
7.0.x	7.0	7.2

我建议你养成一个好习惯：每次升级 AGP 之前，先去官方文档看一眼对应的 Gradle 版本要求。别升完 AGP 再升 Gradle，一步到位反而省事。

下面这张图帮你把排查流程理清楚了——从报错开始，到最终修复，每一步该做什么：

1.4 如何检查当前版本

排查的第一步，是先搞清楚项目里用的 AGP 和 Gradle 到底是什么版本。我一般会先打开这两个文件：

AGP 版本：定义在项目根目录的 build.gradle 或 build.gradle.kts 中。

// 根 build.gradle (Groovy)
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.1.4"
    }
}

// 或 build.gradle.kts (Kotlin DSL)
plugins {
    id("com.android.application") version "8.1.4" apply false
}

Gradle 版本：定义在 gradle/wrapper/gradle-wrapper.properties 中。

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

我个人习惯把这两个文件同时打开，对照着看。一个显示 AGP 版本号，一个显示 Gradle 版本号。拿 AGP 版本去查上面那张表，马上就知道 Gradle 版本对不对。

另外，你也可以通过命令行快速查看：

# 查看 Gradle 版本
./gradlew --version

# 查看 AGP 版本（会输出所有已解析的插件版本）
./gradlew buildEnvironment

命令行输出的信息更全，但日常开发中，直接看文件更快。

1.5 解决方案与避坑指南

发现版本不匹配之后，解决办法其实就两条路：

升级 Gradle 版本：修改 gradle-wrapper.properties 里的 distributionUrl，指向兼容的 Gradle 版本。然后重新 Sync。
降级 AGP 版本：把 build.gradle 里的 AGP 版本号改低，匹配当前的 Gradle 版本。

该走哪条路？看你的项目实际情况：

如果项目还在开发中，没有复杂的 Gradle 自定义逻辑，优先升级 Gradle。新版本通常性能更好，Bug 更少。
如果项目有很多自定义 Task 或 Plugin，升级 Gradle 可能引入兼容性问题。这时候降级 AGP 更稳妥。
如果 AGP 版本太老（比如 4.2.x），第三方库已经开始要求更高版本，那只能硬着头皮升级 Gradle。

⚠️ 升级 Gradle 版本时要注意：Gradle 大版本升级（比如 7.x → 8.x）可能会废弃一些 API。你需要在升级后执行一次完整的构建，看看有没有 Deprecation 警告。别等到上线那天才发现问题。

我在项目中遇到过最离谱的一次，是同事不小心把 AGP 从 7.4 升到了 8.1，但 Gradle 还锁在 7.5。结果 CI 流水线炸了整整一天，所有人都以为是网络问题。最后我花了两分钟查版本号，改了一行配置就解决了。

避坑指南：我曾经因为版本问题折腾了一整个下午，后来总结了一个原则——「升级 AGP 之前，先查 Gradle 兼容表；升级 Gradle 之后，立刻跑一遍完整构建」。这两个动作加起来不超过十分钟，但能省掉后面数小时的排查时间。

另外，如果你用的是 Android Studio，IDE 其实会帮你检查版本匹配情况。在 File → Project Structure → Project 菜单里，能看到 AGP 和 Gradle 的版本号，并且会有提示告诉你是否兼容。嗯，这个入口很多人不知道，其实挺方便的。

好了，这一章的重点就是这些。版本匹配的问题，说穿了就是「查表 + 对版本号 + 调整」三步。只要养成检查版本对应关系的习惯，这类构建失败基本不会再困扰你。