如何解决Flutter中的JDK与Gradle配置错误

问题现象 #

运行多个Flutter项目（包括新建项目）时均出现相同构建错误，核心提示为无法解析com.android.tools.build:gradle:8.1.0，即使已在zsh和bash环境配置JDK 11仍无法解决。

完整报错日志：

ashvinstech@Ashvins-MacBook-Air untitled1 % flutter run
Launching lib/main.dart on Redmi Note 7 in debug mode...

FAILURE: Build failed with an exception.

* What went wrong:
Could not resolve all files for configuration 'classpath'.
> Could not resolve com.android.tools.build:gradle:8.1.0.
  Required by:
      unspecified:unspecified:unspecified > com.android.application:com.android.application.gradle.plugin:8.1.0
   > No matching variant of com.android.tools.build:gradle:8.1.0 was found. The consumer was configured to find a library for use during runtime, compatible with Java 8, packaged as a jar, and its dependencies declared externally, as well as attribute 'org.gradle.plugin.api-version' with value '8.3' but:
       - Variant 'apiElements' capability com.android.tools.build:gradle:8.1.0 declares a library, packaged as a jar, and its dependencies declared externally:
           - Incompatible because this component declares a component for use during compile-time, compatible with Java 11 and the consumer needed a component for use during runtime, compatible with Java 8
           - Other compatible attribute:
               - Doesn't say anything about org.gradle.plugin.api-version (required '8.3')
       - Variant 'javadocElements' capability com.android.tools.build:gradle:8.1.0 declares a component for use during runtime, and its dependencies declared externally:
           - Incompatible because this component declares documentation and the consumer needed a library
           - Other compatible attributes:
               - Doesn't say anything about its target Java version (required compatibility with Java 8)
               - Doesn't say anything about its elements (required them packaged as a jar)
               - Doesn't say anything about org.gradle.plugin.api-version (required '8.3')
       - Variant 'runtimeElements' capability com.android.tools.build:gradle:8.1.0 declares a library for use during runtime, packaged as a jar, and its dependencies declared externally:
           - Incompatible because this component declares a component, compatible with Java 11 and the consumer needed a component, compatible with Java 8
           - Other compatible attribute:
               - Doesn't say anything about org.gradle.plugin.api-version (required '8.3')
       - Variant 'sourcesElements' capability com.android.tools.build:gradle:8.1.0 declares a component for use during runtime, and its dependencies declared externally:
           - Incompatible because this component declares documentation and the consumer needed a library
           - Other compatible attributes:
               - Doesn't say anything about its target Java version (required compatibility with Java 8)
               - Doesn't say anything about its elements (required them packaged as a jar)
               - Doesn't say anything about org.gradle.plugin.api-version (required '8.3')

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 53s
Running Gradle task 'assembleDebug'...                             62.2s
Error: Gradle task assembleDebug failed with exit code 1
ashvinstech@Ashvins-MacBook-Air untitled1 % 

解决方案 #

1. 对齐Gradle与AGP版本 #

AGP 8.1.0要求Gradle版本范围为8.0-8.2，当前项目使用的Gradle 8.3与该版本不兼容。修改项目根目录下的gradle/wrapper/gradle-wrapper.properties文件：

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

2. 明确项目Java版本配置 #

确保项目强制使用JDK 11，修改android/build.gradle文件：

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = '11'
    }
}

同时在android/gradle.properties中指定JDK 11的实际路径（替换为你的本地路径）：

org.gradle.java.home=/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home

3. 清理缓存并重新构建 #

执行以下命令清理本地缓存，避免旧缓存干扰：

flutter clean
rm -rf android/.gradle
rm -rf ~/.gradle/caches
flutter pub get
flutter run

原因分析 #

• AGP与Gradle版本存在严格对应关系，AGP 8.1.0不兼容Gradle 8.3；
• 虽然系统已配置JDK 11，但项目未明确指定Java版本，Gradle可能默认使用Java 8，与AGP 8.x要求的Java 11冲突。

内容的提问来源于stack exchange，提问作者Ashvin Bhagat