Flutter 项目中 Gradle 与 Java 版本不兼容的解决

问题描述

当你在更新 Android Studio 后运行 Flutter 项目时，可能遇到以下错误：

FAILURE: Build failed with an exception.
* What went wrong: Could not open settings generic class cache for settings file '.\android\settings.gradle'
> BUG! exception in phase 'semantic analysis' in source unit 'BuildScript' Unsupported class file major version 61

此问题通常由以下原因导致：

• 更新 Android Studio 后 JDK 版本自动升级（例如 JDK 17→21）
• Flutter 项目使用的 Gradle 版本过低（例如 6.x）不支持新版 Java
• Android Studio 自带的 JDK 与本地环境中的 JDK 产生冲突
• Gradle Wrapper 配置未更新为兼容版本

解决方案

方法一：更新 Gradle 版本（推荐）

兼容性参考

根据 Gradle 官方兼容性矩阵：

• Java 17 → Gradle 7.3+
• Java 21 → Gradle 8.5+

1. 修改 Gradle Wrapper 打开项目中的 android/gradle/wrapper/gradle-wrapper.properties 文件

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip

2. 更新 Android Gradle Plugin(AGP) 修改 android/build.gradle 中的 AGP 版本：

   dependencies {
       // 确保版本≥8.3.2
       classpath 'com.android.tools.build:gradle:8.3.2'
       // 其他依赖...
   }

3. 设置 JDK 版本 在 android/gradle.properties 中明确指定 Java 17：

   org.gradle.java.home=/path/to/jdk-17

   如何查找 JDK 17 路径？

方法二：通过命令行更新

在项目中的 android 目录运行：

# Windows
gradlew wrapper --gradle-version 8.5

# Linux/macOS
./gradlew wrapper --gradle-version 8.5

方法三：配置 Flutter 专用 JDK

flutter config --jdk-dir="/path/to/jdk-17"

验证配置：

flutter doctor -v

方法四：使用 Android Studio 向导

1. 在 Android Studio 中单独打开 android 目录
2. 接受 IDE 的升级建议
3. 跟随向导完成 Gradle 和 AGP 升级
4. 执行项目清理：

flutter clean
flutter pub get

如何定位 JDK 安装路径

Linux/macOS (sdkman)

sdk list java  # 查找已安装的 JDK
echo "$HOME/.sdkman/candidates/java/17.0.11-amzn"  # 获取具体路径

Windows (PowerShell)

Get-Command java | Select-Object -ExpandProperty Path

macOS (手动定位)

/Applications/Android Studio.app/Contents/jbr/Contents/Home

验证兼容性

检查 Java 与 Gradle 版本兼容：

cd android
./gradlew --version  # 查看构建环境详情

升级后清理操作

flutter clean
flutter pub cache repair
flutter pub get

常见错误与处理

注意事项

1. 升级 Gradle 后需同步升级 com.android.tools.build:gradle 插件
2. Flutter 默认优先使用 Android Studio 自带的 JDK
3. Java 版本需在项目的 app/build.gradle 中声明

   compileOptions {
       sourceCompatibility JavaVersion.VERSION_17
       targetCompatibility JavaVersion.VERSION_17
   }

当项目依赖未更新时可能见到：

Could not determine java version from '21'

此时需检查 android/gradle/wrapper/gradle-wrapper.properties 中 URL 是否指向 8.5+ 版本

替代方案：使用新项目模板

创建新 Flutter 项目，复制其 android/gradle 目录配置到现有项目，通常包含：

• 最新的 Gradle Wrapper 配置
• 兼容的 AGP 版本设置
• 当前推荐的编译参数

通过上述解决方案升级到兼容版本组合（Java 17+ 配 Gradle 8.5+），即可消除版本冲突错误，恢复正常构建。