Gradle 与 Java 版本不兼容问题：'Unsupported class file major version' 修复指南

问题概述

当在 Apple Silicon (ARM) Mac 或其他平台上运行 Flutter 或 Android 项目时，可能会遇到以下错误：

BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 61

这个错误通常出现在升级 Android Studio、Java 版本或 Gradle 后，表示当前使用的 Gradle 版本与 Java 版本不兼容。

根本原因

此问题的核心原因是 Gradle 版本与 Java 版本不匹配。Gradle 每个版本都支持特定的 Java 版本范围，使用不兼容的组合会导致构建失败。

"major version" 数字对应 Java 版本：

• 61 → Java 17
• 65 → Java 21
• 其他数字对应不同 Java 版本

解决方案

方法一：升级 Gradle 版本（推荐）

这是最直接和持久的解决方案，确保 Gradle 版本与您的 Java 版本兼容。

1. 确定当前 Java 版本

   java -version

2. 检查兼容性 参考 Gradle 官方兼容性矩阵：

   Java 版本	最低支持 Gradle 版本
   8	2.0
   9	4.3
   11	5.0
   17	7.3
   18	7.5
   19	7.6
   21	8.5

3. 修改 Gradle 配置 在 android/gradle/wrapper/gradle-wrapper.properties 文件中更新 distributionUrl：

   # 将版本号改为与您 Java 版本兼容的 Gradle 版本
   distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip

4. 更新 Android Gradle 插件 在 android/build.gradle 中更新依赖：

   dependencies {
       classpath 'com.android.tools.build:gradle:8.3.0' // 与 Gradle 版本兼容
   }

方法二：配置 Flutter 使用特定 JDK

如果您的系统有多个 Java 版本，可以指定 Flutter 使用特定的 JDK：

# 查看已安装的 Java 版本
/usr/libexec/java_home -V

# 设置 Flutter 使用的 JDK 路径
flutter config --jdk-dir '/path/to/your/jdk'

例如：

flutter config --jdk-dir '/Library/Java/JavaVirtualMachines/jdk-17.0.12/Contents/Home'

方法三：清理 Gradle 缓存

有时 Gradle 缓存损坏会导致此问题：

1. 删除 Gradle 缓存目录

   • macOS/Linux: ~/.gradle/caches/
   • Windows: %USERPROFILE%\.gradle\caches\

2. 或在 Android Studio 中清理

   • 进入 Settings → Build, Execution, Deployment → Build Tools → Gradle
   • 找到 "Gradle user home" 路径并清理该目录

方法四：在项目中指定 Java 版本

在 android/gradle.properties 中添加：

# 指定项目使用的 Java 主目录
org.gradle.java.home=/path/to/your/jdk

预防措施

1. 保持工具链同步

   • 定期检查 Gradle-Java 兼容性表
   • 在升级 Java 前确认当前 Gradle 版本是否支持新版本

2. 使用项目专属配置

   • 在项目中指定 Java 版本而非依赖系统全局设置
   • 使用 .jvmtoolchain 文件或 gradle.properties 配置

3. 团队协作一致性

   • 确保团队成员使用相同的开发环境配置
   • 版本控制中包含环境配置文件

常见问题解答

Q: 如何检查 Flutter 当前使用的 Java 版本？ A: 运行 flutter doctor -v 并在 "Android toolchain" 部分查看 "Java binary at:" 信息。

Q: 升级 Gradle 后出现其他错误怎么办？ A: 可能需要同步更新 Android Gradle Plugin 版本，参考 Android Gradle Plugin 与 Gradle 版本对应关系。

Q: 是否应该降级 Java 版本？ A: 不推荐。优先升级 Gradle 以支持较新的 Java 版本，因为新版本有更好的性能和安全性。

总结

Unsupported class file major version 错误通常通过以下步骤解决：

1. 确认 Java 版本与 Gradle 版本的兼容性
2. 升级 Gradle 到兼容版本
3. 必要时清理 Gradle 缓存
4. 确保开发环境配置一致

保持开发工具链的版本兼容性是避免此类问题的关键。定期查看官方兼容性文档，并在升级任何组件前做好兼容性检查。

最佳实践

建议使用版本管理工具（如 SDKMAN! 或 jenv）管理多个 Java 版本，以便在不同项目间轻松切换。

如需更多帮助，请参考：

• Gradle 官方文档
• Android 开发者文档
• Flutter 文档