Gradle是通用构建引擎，AGP是Android专用插件；Gradle负责任务调度与依赖管理，本身不识别Android特有概念，AGP通过注册Android专属任务（如mergeDebugResources、transformDexArchiveWithDexMergerForDebug）并提供android{...} DSL，使Gradle具备编译APK、处理资源、生成R.java等能力；二者版本必须严格匹配，错配将导致sync失败或构建异常。
Gradle 和 Android Gradle Plugin（AGP）不是同一层的东西，混淆它们会导致 build 失败、版本冲突、甚至无法 sync 项目。
Gradle 是构建引擎，AGP 是 Android 专用任务包
Gradle 是通用构建工具，负责执行 task、管理依赖、解析 build.gradle 脚本。它本身完全不认识 AndroidManifest.xml、R.java、APK 这些概念。
AGP（即 com.android.application 或 com.android.library 插件）才是让 Gradle “懂 Android” 的关键——它向 Gradle 注册了一堆 Android 特有的 task（比如 mergeDebugResources、transformDexArchiveWithDexMergerForDebug），并提供 android { ... } 块的 DSL 支持。
类比：Gradle 是汽车发动机，AGP 是专为越野车定制的变速箱 + 差速锁 + 油箱适配器；没 AGP，Gradle 就是台空转的发动机，跑不了 Android 项目。
版本必须严格匹配，不匹配会直接报错
AGP 依赖特定范围的 Gradle 版本，不是“越高越好”或“随便凑合”。例如：
-
AGP 8.4要求Gradle 8.6，用Gradle 8.5会提示：Minimum supported Gradle version is 8.6 -
AGP 7.2不支持Gradle 8.0+，会抛出No such property: android for class: org.gradle.api.Project
匹配表不在文档里硬背，而是查官方页面：https://developer.android.com/studio/releases/gradle-plugin#compatibility-versions。每次升级 AGP 前，先改 gradle-wrapper.properties 里的 distributionUrl，再改 build.gradle 里的 classpath。
配置位置和修改方式完全不同
Gradle 版本由 gradle-wrapper.properties 控制：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
AGP 版本由项目级 build.gradle（或 build.gradle.kts）中的 dependencies 块控制：
dependencies {
classpath 'com.android.tools.build:gradle:8.4.0'
}
常见错误包括：
- 只升级了
gradle-wrapper.properties却忘了改classpath→ 同步失败 - 在模块级
build.gradle里写classpath→ 无效，Gradle 找不到插件 - 用了
all包但本地磁盘空间不足 → 解压失败，卡在 wrapper 下载阶段
AGP 升级常触发隐性破坏，Gradle 升级更偏底层兼容
AGP 升级影响更直接可见：
-
compileSdkVersion可能被强制要求更新 -
android.useAndroidX默认变为true，旧 support 库引用直接编译报错 -
variant.getJavaCompile()等 API 被移除 → 自定义插件或脚本崩掉
Gradle 升级则更隐蔽：
- Groovy DSL 中
it引用行为变化（如tasks.withType(JavaCompile)返回类型不同） -
gradle.properties中的org.gradle.configuration-cache=true在高版本 AGP 下可能与某些插件不兼容
真正麻烦的是：AGP 和 Gradle 升级常常要一起做，但错误日志往往只报最外层异常，实际根因在版本错配。建议每次只动一个，成功 sync 后再动另一个。
