3. Gradle 版本兼容性：不同AGP对应Gradle版本、兼容性矩阵

这事儿其实挺让人头疼的。你想想看，Android构建系统里，AGP和Gradle这两个东西就像一对跳探戈的搭档，步伐必须得合拍。节奏一乱，整个项目就卡在那了。我当年刚入行时，就被这个“版本兼容性”坑过好几次。

为什么版本必须“对号入座”？

说白了，AGP（Android Gradle Plugin）和Gradle这两个东西，是深度绑定的。Android官方每发一个新版本的AGP，都会去测试它对特定Gradle版本的兼容性。你用了一个AGP 8.x，却配了一个Gradle 7.x的尾缀版本，构建肯定会报错。

为什么会这样？因为AGP内部大量使用了Gradle新的API。Gradle升级后，旧API可能会被标记为@Deprecated，甚至直接移除。没有跟上版本，你的构建脚本就可能炸掉。

AGP 版本	最低 Gradle 版本	推荐 Gradle 版本	说明
8.7	8.9	8.10+	新项目首选，要求 Gradle 必须跟上节奏
8.6	8.7	8.8+	我建议如果你在升级，从这版开始踩稳
8.5	8.7	8.8+	稳定；搭配 Gradle 8.8 我遇到过一些 Kotlin DSL 的奇怪问题
8.4	8.6	8.7+	上一代主力，现在部分 CI 还在用
8.3	8.4	8.5+	很多老项目停在 8.3+8.5 这一对
8.2	8.2	8.4+	边缘版本，不推荐新项目使用
8.1	8.0	8.2+	已淘汰；用于某些必须锁版本的 legacy 项目

配置方法

代码上怎么改？很简单，在 gradle-wrapper.properties 里指定 Gradle 版本：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

然后在项目根目录的 build.gradle（根级）里设置 AGP 版本：

plugins {
    id 'com.android.application' version '8.7.3' apply false
    id 'com.android.library' version '8.7.3' apply false
    // ...
}

我个人习惯直接写死大版本号后两位的 patch 版本，比如 8.7.3。这样就避免了因为 patch 自动升级导致的未知兼容问题。

具体策略

• 新项目：直接把 AGP 拉满到最新稳定版，对应的 Gradle 版本也拉满。我建议你同时更新一下 Android Studio，这样就省去很多适配的麻烦。
• 旧项目升级：不要一下跨越太多版本。比如从 AGP 7.2 升到 8.7，我会分成两步：先升到 8.0，测试通过后，再升到 8.7。这一步我踩过坑——直接跳版本升级，一堆 API 报错，根本搞不清是哪个 diff 引入的。
• CI / CD 场景：CI 环境里一定要固定 Gradle Wrapper 的版本。我曾经在跑 CI 时遇到过这样的情况：本地 build 通过，CI 却失败。排查了好久，发现 CI 的 Gradle 版本跟本地的 wrapper 里的版本不一致。所以 CI 里要显式设置：
  distributionUrl 和 gradle-version，并且在 pipeline 脚本里强制校验：
  ./gradlew --version | grep "Gradle 8.10.2"。

AGP & Gradle 兼容性全貌

为了让你一目了然，我把核心逻辑画成了一张图。这是 AGP 8.x 与 Gradle 版本的对应关系，同时也标出了常见的踩坑点：

这张图左边是AGP不同大版本，右边是对应的推荐 Gradle 版本。底部的验证步骤，是我在每个项目升级完配置后都会跑一遍的流程。你想想看，如果你能固守这些原则，版本兼容问题基本就不会再拦着你了。