AGP版本升级必须先满足其最低Gradle约束：AGP 8.13要求Gradle≥8.13，AGP 9.0强制要求Gradle≥9.1.0，否则报错“This version of Android Gradle Plugin requires a newer Gradle version”。
确认 Android Gradle Plugin（AGP）版本要求
Gradle 升级不是独立行为，它必须先满足当前项目所用 AGP 的最低版本约束。AGP 8.13 要求 Gradle ≥ 8.13，AGP 9.0 则强制要求 Gradle ≥ 9.1.0——低于这个值会直接报错 This version of Android Gradle Plugin requires a newer Gradle version。
检查方式很简单：
打开项目根目录的 build.gradle（或 build.gradle.kts），定位到 dependencies 块里的 classpath 'com.android.tools.build:gradle:x.x.x'，这就是你的 AGP 版本。
- 不要只看 AGP 版本号就去查“最新 Gradle”，要查官方明确标注的 最低兼容 Gradle 版本
- AGP 9.0 开始已移除对旧 DSL 类（如
BaseExtension）的支持，若项目里有自定义插件或构建脚本依赖这些类，升级 Gradle 前必须先适配 AGP 9.0 的新接口 - Android Studio 2024.2+ 默认推荐 AGP 9.0+，但如果你还在用旧版 AS，强行升 Gradle 可能导致 IDE 同步失败，连
Sync Project按钮都变灰
核对 JDK 版本是否匹配
Gradle 8.x 支持 JDK 8–20，Gradle 9.x 则要求 JDK 17–21。而 AGP 9.0 明确要求 JDK 17 为最低版本——这意味着即使你装了 JDK 21，只要项目配置里没显式指定，Gradle 运行时仍可能 fallback 到系统默认 JDK（比如旧版 Android Studio 自带的 JDK 11），结果就是 Could not determine java version from '11.0.22' 这类错误。
验证方法：
运行 ./gradlew --version，输出里会显示 JVM: 行，它才是 Gradle 实际使用的 JDK；java -version 只是 shell 当前环境的 JDK，二者可能不一致。
- 在
gradle.properties中设置org.gradle.java.home=/path/to/jdk-17是最稳妥的绑定方式 - Android Studio 的 JDK 配置（File > Project Structure > SDK Location）只影响 IDE 自身和模拟器，不影响 Gradle 构建过程
- 如果用了
org.jetbrains.kotlin.android插件，注意它与 AGP 9.0 的新 DSL 不兼容，KMP 项目需改用com.android.library+ KMP Library Plugin 组合
扫描第三方插件与自定义任务的 API 兼容性
Gradle 7.0 引入配置缓存（configuration cache），8.0 进一步收紧序列化规则，9.0 则默认启用并限制更严。任何使用了 project.afterEvaluate、反射访问 Project 内部字段、或在 task action 中读取未声明输入/输出的插件，都会在启用配置缓存后直接失败，报错类似 Task ':app:assembleDebug' is not up-to-date because property 'someField' has no annotation。
常见高危点：
— 使用 com.github.ben-manes.versions 插件的老版本（≤ 0.47.0）不兼容 Gradle 8.5+
— 自定义 lint 规则中调用 LintClient 的非公开构造函数
— Fresco OSS 构建中引用 com.meta.* 或内部 Litho API（如 PrimitiveImage），这些在开源 Gradle 环境下根本不可见
- 本地调试时加
--scan参数（./gradlew assembleDebug --scan）可生成构建分析报告，自动标出禁用 API 调用点 - 对插件做兼容性兜底：在
gradle.properties中临时加org.gradle.configuration-cache=false，但这只是绕过问题，不是解决 - 如果项目含大量
buildSrc逻辑，务必检查其中是否用了已废弃的TaskInputs.files()等 API，它们在 Gradle 9 中已被filesProperty替代
验证依赖解析链是否断裂
Gradle 升级常伴随依赖解析引擎变更。例如从 6.x 到 7.x，Maven BOM（Bill of Materials）支持更严格，某些未声明 import scope 的 BOM 会导致 Could not resolve all dependencies；而 8.x 开始默认启用 dependency verification，若项目没配 gradle/verification-metadata.xml，又引用了未签名的 SNAPSHOT 包，构建会直接中断。
典型现象：
— implementation 'androidx.core:core-ktx' 编译通过，但运行时报 NoClassDefFoundError，其实是 transitive 依赖被新版解析策略排除了
— Mockito-Kotlin 4.x 要求 Kotlin 1.9+，而 Kotlin 插件版本又受 Gradle 版本制约，形成隐式依赖环
- 用
./gradlew app:dependencies --configuration debugCompileClasspath查看实际解析出的依赖树，比 IDE 的 “External Libraries” 更真实 - 如果项目用了
force或exclude手动干预依赖，升级后要重验——Gradle 新版可能忽略这些指令，或以不同优先级处理 - Fresco OSS 构建失败常源于
buildSrc/src/main/java/com/facebook/fresco/buildsrc/dependencies.kt中硬编码的 Litho 0.50.1 版本，任何试图引入更高版 Litho API 的改动都会在 CI 阶段被拦截
Gradle 升级真正难的不是改几个版本号，而是那些藏在构建脚本深处、只在特定 Gradle 版本下才暴露的隐式契约：比如某个 task 的 outputs.dirs 在 7.x 是可写属性，在 9.x 必须用 directoryProperty 声明；又比如 compileSdkVersion 在 AGP 9.0 中已不允许设为字符串字面量。这些细节不会报错提示“请升级”，只会让构建静默失败或行为异常。
