2. AGP 与 Gradle 版本兼容矩阵配置
为什么 AGP 与 Gradle 必须成对选择
Android Gradle Plugin（AGP）运行在 Gradle 之上，它调用的 Gradle API 随 Gradle 版本演进。AGP 每个大版本都声明了最低 Gradle 版本，低于该版本会在同步阶段直接报错；而 Gradle 版本过高时，旧 AGP 也可能因 API 移除而失败。因此配置顺序是：先定 AGP 版本 → 再查其要求的最低 Gradle 版本 → 在 Wrapper 中锁定该 Gradle 版本。
配置实操：以 AGP 8.2.x 为例
假设工程使用 AGP 8.2.2，查矩阵可知最低 Gradle 为 8.2。先改 Wrapper，再改根构建脚本，最后同步验证。
第一步：锁定 Gradle 发行版，编辑 gradle/wrapper/gradle-wrapper.properties：
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists关键行是 distributionUrl，其中 gradle-8.2-bin.zip 的 8.2 就是被锁定的 Gradle 版本。若团队要求可复现性，可追加 distributionSha256Sum=<官方校验值>。
第二步：声明 AGP 版本，在根 build.gradle 的 plugins 块中指定：
plugins {
id 'com.android.application' version '8.2.2' apply false
id 'com.android.library' version '8.2.2' apply false
}模块级 build.gradle 只写 id 'com.android.application'，不带 version，版本由根脚本统一管理，避免多模块版本漂移。
若使用 Kotlin DSL，写法为
id("com.android.application") version "8.2.2" apply false，语义完全一致。同步与验证
- 执行
./gradlew --version，确认输出Gradle 8.2，说明 Wrapper 已生效。 - 在 Android Studio 中点击 Sync Now，或在命令行执行
./gradlew help触发配置阶段。 - 观察结果：同步成功即表示 AGP 8.2.2 与 Gradle 8.2 兼容。
典型报错
Minimum supported Gradle version is 8.2. Current version is 7.5. 说明 Wrapper 版本低于 AGP 要求，按提示把 distributionUrl 提升到 8.2 或更高即可，不要反向降低 AGP 版本除非有明确约束。版本选择速查表
| AGP 版本 | 最低 Gradle | distributionUrl 片段 |
|---|---|---|
| 8.7.x | 8.9 | gradle-8.9-bin.zip |
| 8.5.x | 8.7 | gradle-8.7-bin.zip |
| 8.2.x | 8.2 | gradle-8.2-bin.zip |
| 8.0.x | 8.0 | gradle-8.0-bin.zip |
| 7.4.x | 7.5 | gradle-7.5-bin.zip |
| 7.0.x | 7.0 | gradle-7.0-bin.zip |
表中“最低 Gradle”是硬性下限，实际可略高于该值，但需确认 AGP 未使用被移除的 API；生产工程建议取最低值或官方推荐值，减少不确定性。