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

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

嗯，今天咱们聊个很常见但也容易栽跟头的问题——AGP 和 Gradle 的版本匹配。说白了，Android Gradle Plugin 和 Gradle 本身是两个独立的软件，它们之间有一套严格的对应关系。一旦你没对齐，构建就直接崩给你看。

你大概率见过的报错

我接手过不少项目的“修复构建”需求，最典型的报错长这样：

What went wrong:
The Android Gradle Plugin supports only Kotlin Gradle Plugin version X.Y.Z and higher.
The following dependencies do not satisfy the required version:
project ':app' - Kotlin Gradle Plugin 1.3.72

或者：

Execution failed for task ':app:compileDebugKotlin'.
> Could not resolve all files for configuration ':app:debugCompileClasspath'.
   > Could not resolve org.jetbrains.kotlin:kotlin-stdlib:1.4.0.
     Required by:
         project :app
> No matching variant of org.jetbrains.kotlin:kotlin-stdlib:1.4.0 was found.

还有更直接的：

The Android Gradle plugin requires Gradle X.Y.Z or higher.
Current version is X.Y.Z.

这些报错信息其实已经很清楚——AGP 告诉你它需要的 Gradle 版本是多少，但你的项目里没用对。很多新手拿到报错第一反应是去改 Gradle 版本，但改了之后又冒出其他冲突，陷入死循环。

为什么会不匹配？

原因很简单：每个 AGP 版本在发布时，都针对某一个 Gradle 版本做了测试和优化。如果用太老的 Gradle，新 AGP 的功能可能不兼容；用太新的 Gradle，老 AGP 又不认识。我也踩过这个坑：有次为了用 AGP 8.0 的新特性，顺手把 Gradle 升到了 8.5，结果构建时冒出一堆“Configuration cache”相关警告，折腾了俩小时才发现是 Gradle 版本超前了。

核心原则：AGP 和 Gradle 的版本号不是可以随意组合的。官方在每个 AGP 版本的发布说明里都明确标注了最低 Gradle 版本和推荐 Gradle 版本。

官方兼容性对照表

下面是 AGP 7.x ~ 8.x 与 Gradle 的对应关系（截至写稿时，最新的稳定版本）：

AGP 版本	最低 Gradle 版本	推荐 Gradle 版本
8.7	8.9	8.9
8.6	8.7	8.7
8.5	8.7	8.7
8.4	8.6	8.6
8.3	8.4	8.4
8.2	8.2	8.2 – 8.3
8.1	8.0	8.0 – 8.1
8.0	8.0	8.0 – 8.1
7.4	7.5	7.5 – 7.6
7.3	7.4	7.4 – 7.5
7.2	7.3.3	7.3.3 – 7.4
7.1	7.2	7.2 – 7.3
7.0	7.0	7.0 – 7.2

我的习惯：每当要升级 AGP，我会先打开 https://developer.android.com/build/releases/gradle-plugin#compatibility 看一眼兼容性表，然后直接设成推荐版本。别凭感觉选，除非你想花半小时排查。

诊断流程——一张图搞定

下面这张图帮我不少同事快速定位问题。你可以照着这个流程走一遍：

具体怎么改？

知道了兼容性表，修改就很简单了。找到项目根目录下的 gradle/wrapper/gradle-wrapper.properties 文件：

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

把 gradle-8.7-bin.zip 换成兼容性表里推荐的版本号。比如你用的 AGP 8.5，就把版本改成 8.7。

然后还要检查项目级 build.gradle 或 build.gradle.kts 里的 AGP 版本：

// 在 top-level build.gradle 中
buildscript {
    dependencies {
        classpath "com.android.tools.build:gradle:8.5.0"
    }
}

或者用 Kotlin DSL：

// 在 build.gradle.kts 中
plugins {
    id("com.android.application") version "8.5.0" apply false
}

确保 AGP 版本和 Gradle 版本在官方兼容性表内，然后 clean + rebuild。

注意：升级 Gradle 版本后，如果项目里用了自定义 Task 或第三方插件，可能会遇到不兼容。我建议先只改 AGP 和 Gradle 版本，确认构建通过后再逐步升级其他插件。

避坑指南：我曾经踩过的雷

忘了更新 Gradle Wrapper：只改了 gradle-wrapper.properties 里的 URL，但本地缓存里还是旧版本？用 ./gradlew wrapper --gradle-version=8.7 命令强制刷新。
Kotlin 插件版本也在捣乱：AGP 8.5 要求 Kotlin 插件不低于 1.9.0，如果项目里用了 1.8.x，构建会报“Kotlin Gradle Plugin 版本太低”。这时候需要同步升级 org.jetbrains.kotlin.android 的版本。
把 Gradle 和 AGP 顺序搞反了：有人看到报错说“AGP requires Gradle 8.7”，反手把 AGP 版本降级了——这可能是临时的解法，但如果你想要新特性，还是建议升级 Gradle。

说了这么多，其实就一句话：版本对齐是构建的第一步。我希望你以后遇到类似报错，能直接按流程图走一遍，别在 git 里乱改版本然后又后悔。我个人习惯把兼容性表存成书签，每次升级前看一眼，省心。