Gradle兼容性测试必须修改gradle-wrapper.properties并清理缓存，配合org.gradle.java.home精确指定JDK，通过./gradlew clean build --no-daemon验证各任务实际执行效果，而非仅依赖--version或IDE提示。
直接用 ./gradlew --version 看当前环境能跑通哪个 Gradle 版本，毫无意义——它只反映本地缓存和 JAVA_HOME 的现状，不是项目真实兼容边界。真正要测的是：给定一个项目（含 gradle-wrapper.properties），换不同 Gradle 版本时构建是否稳定、插件是否加载、任务是否可执行。
改 gradle-wrapper.properties 是最简验证方式
这是所有兼容性测试的起点，也是唯一可靠的手动方法。不要依赖 IDE 自动提示或“升级建议”，它们常滞后或误判。
-
distributionUrl必须指向完整 URL，例如https\://services.gradle.org/distributions/gradle-8.5-bin.zip，不能省略-bin.zip后缀，否则下载失败 - 改完后务必删掉
~/.gradle/wrapper/dists/下对应旧版本缓存目录（如gradle-7.6-bin/xxx），否则 Gradle 可能复用损坏或不匹配的缓存 - 执行
./gradlew clean build --no-daemon -Dorg.gradle.debug=false：禁用 daemon 避免残留状态干扰；--no-daemon能暴露 JVM 初始化阶段的真实兼容问题
遇到 Unable to find method 'org.gradle.api...' 怎么定位
这不是 Gradle 本身坏了，而是某个插件编译时绑定的 Gradle API 版本，和当前运行的 Gradle 不一致。错误栈里出现 ComponentSelectionReason.getDescription() 或 ProjectLayout.getBuildDirectory() 找不到，基本可锁定为插件 ABI 不兼容。
- 先运行
./gradlew buildEnvironment，检查输出中classpath下所有插件的传递依赖，重点关注带->的版本重定向，比如com.android.tools.build:gradle:7.4.2 -> 8.0.0 - 再查各插件官网的兼容矩阵，例如 AGP 8.0+ 要求 Gradle 8.0+，而
com.google.dagger.hilt.android2.45 要求 AGP ≥ 7.4 —— 如果你硬把 AGP 降级到 7.3，Hilt 插件就会触发该报错 - 临时排除法：注释掉非核心插件（如 Firebase、Crashlytics、Hilt），只留
com.android.application和org.jetbrains.kotlin.android，确认基础构建是否通过
多 JDK + 多 Gradle 组合必须显式控制 JVM
Gradle Wrapper 不管你用什么 JDK 运行它，它只负责下载并启动自己的 Gradle 实例；但这个实例的 JVM 由 org.gradle.java.home 决定 —— 如果没设，就用当前 shell 的 JAVA_HOME，极易和项目实际需要的 JDK 版本错位。
- 在项目根目录的
gradle.properties中强制指定：org.gradle.java.home=/path/to/jdk-17.0.2（路径必须精确到 JDK 根目录，不能是 JRE） - Android Studio 用户注意：IDEA 的 “Gradle JVM” 设置（Settings > Build > Build Tools > Gradle）只影响 IDE 内部的构建进程，不影响终端执行
./gradlew；两者必须一致，否则出现“终端能过、IDE 报错”这类撕裂现象 - 验证是否生效：加
--info参数运行构建，搜索日志里的Starting Daemon with Java version，确保显示的是你预期的 JDK 版本
真正的兼容性边界不在文档表格里，而在 gradle-wrapper.properties 和 org.gradle.java.home 的组合执行结果中。每次切换版本后，别只看 BUILD SUCCESSFUL，还要确认 test、assembleDebug、compileKotlin 这些关键任务是否真能跑通——有些插件会在特定 task 阶段才暴露 ABI 问题。
