Gradle与OpenJDK必须双向匹配，仅升级JDK不验证Gradle兼容性易致“Unsupported Java”错误；需同步检查Gradle Wrapper版本、AGP限制、IDE Gradle JVM设置及JAVA_HOME，并通过gradle --version和--no-daemon build --dry-run快速验证三者一致性。
Gradle 版本和 OpenJDK 版本必须双向匹配，只升级 JDK 而不验证 Gradle 兼容性，大概率在 gradle build 或 Android Studio 同步时直接报 Unsupported Java 错误。
查 Gradle 官方兼容矩阵不是终点，而是起点
Gradle 官网的 Compatibility Matrix 明确列出了每个 Gradle 版本支持的最低 JDK 版本（例如 Gradle 8.4 要求 JDK 17+），但实际构建失败往往不是因为“不支持”，而是因为：
- IDE 使用的 Gradle JVM（即 Gradle Daemon 运行时用的 JDK）与项目
sourceCompatibility混淆了 - Android 项目中 AGP（Android Gradle Plugin）版本对 JDK 有额外限制（如 AGP 8.5 强制要求 JDK 17，哪怕 Gradle 8.4 本身支持 JDK 21）
- 本地
JAVA_HOME指向旧 JDK，而 IDE 设置里又没显式指定 Gradle JVM，导致 Gradle 自动 fallback 到系统默认 JDK
快速验证当前组合是否真能跑通
别等同步失败再排查。执行以下三步命令，5 秒内就能判断：
1. 确认 wrapper 实际拉取的 Gradle 版本：cat gradle/wrapper/gradle-wrapper.properties | grep distributionUrl
2. 查看该 Gradle 版本声明支持的 JDK 范围：gradle --version（注意看输出里的 JVM 行，它显示的是当前生效的 Gradle JVM，不是项目 SDK）
3. 强制用目标 JDK 运行一次空构建（绕过缓存）：JAVA_HOME=/path/to/jdk-17 ./gradlew --no-daemon build --dry-run
如果这一步报错，说明 Gradle 本身无法在该 JDK 下启动；如果成功，再进下一步。
Android Studio 里最容易被忽略的 Gradle JVM 设置
很多人改完 build.gradle 的 compileOptions.sourceCompatibility 就以为搞定了，但 Android Studio 默认会用自己的捆绑 JDK（4.2+ 是 JDK 11）来运行 Gradle —— 这和你项目代码编译用的 JDK 是两回事。
必须手动指定 Gradle JVM：
- Windows / Linux：
File > Settings > Build, Execution, Deployment > Build Tools > Gradle > Gradle JVM - macOS：
IntelliJ IDEA > Preferences > Build, Execution, Deployment > Build Tools > Gradle > Gradle JVM - 下拉菜单里选你已安装的 JDK 17 或 JDK 21，**不要选 “Project SDK”**（那是给代码编译用的）
改完后点 Sync Project with Gradle Files，观察右下角是否弹出 “Using Gradle JVM: jdk-17.0.x” 提示。
Unity 或老项目升级时的隐性陷阱
Unity 2020.3、旧版 React Native 或 Cordova 项目常自带过期的 Gradle Wrapper（如 gradle-6.1.1），这类项目即使把系统 JDK 升到 17，也会卡在 Unsupported Java version 1.8 —— 因为它的 wrapper 内置逻辑只认 JDK 8。
此时不能只改 JAVA_HOME，必须：
- 先升级
gradle/wrapper/gradle-wrapper.properties中的distributionUrl（如换成gradle-8.5-bin.zip） - 同步更新根目录
build.gradle中的 AGP 版本（如com.android.tools.build:gradle:8.5.0） - 确认新 AGP 版本文档明确支持你的目标
targetSdkVersion（比如 targetSdk 35 需 AGP ≥ 8.4）
漏掉任意一环，都会在打包时突然崩在 Failed to find Build Tools revision 或 Unsupported API level 上。
真正麻烦的从来不是“能不能升”，而是“哪一层配置悄悄覆盖了你刚改好的那一层”。每次 JDK 升级后，务必分别验证 gradle --version 输出的 JVM、IDE 设置里的 Gradle JVM、以及构建日志开头打印的实际启动 JVM 是否三者一致。
