Flutter修复Gradle与Java版本兼容时遭遇新构建故障

已执行操作总结 #

• 检查Java版本：系统安装Java 21.0.5但未配置JAVA_HOME，使用Android Studio自带的Java 21.0.4（来自flutter doctor --verbose输出）
• 参考Gradle兼容矩阵，尝试使用与Java 21匹配的Gradle 8.4和8.5版本
• 进入项目android目录执行./gradlew wrapper --gradle-version=8.4，报错Unsupported class file major version 65，切换Gradle 8.5后问题相同
• 手动修改gradle-wrapper.properties文件，将Gradle版本改为8.5，运行项目时出现D8空指针错误，导致mergeLibDexDebug任务失败

核心错误信息 #

错误1：执行Gradle wrapper命令时 #

Welcome to Gradle 7.6.3!

Here are the highlights of this release:
 - Added support for Java 19.
 - Introduced `--rerun` flag for individual task rerun.
 - Improved dependency block for test suites to be strongly typed.
 - Added a pluggable system for Java toolchains provisioning.

For more details see https://docs.gradle.org/7.6.3/release-notes.html

Starting a Gradle Daemon, 2 incompatible and 1 stopped Daemons could not be reused, use --status for details
> Task :gradle:compileGroovy FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':gradle:compileGroovy'.
> BUG! exception in phase 'semantic analysis' in source unit '/home/ajthapa/dev/tooling/flutter/packages/flutter_tools/gradle/src/main/groovy/app_plugin_loader.groovy' Unsupported class file major version 65

* 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 14s
1 actionable task: 1 executed

错误2：修改wrapper后运行项目时 #

3 warnings
ERROR:/home/ajthapa/dev/projects/flutter/MyAppName/00__Play_Store_builds/00__Closed_Test_version/update__feature_tests/MyAppName_v1.0.29__without_Admob_Ads/nepali_unit_conv/build/path_provider_android/intermediates/runtime_library_classes_jar/debug/classes.jar: D8: java.lang.NullPointerException: Cannot invoke "String.length()" because "<parameter1>" is null

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:mergeLibDexDebug'.
> Could not resolve all files for configuration ':app:debugRuntimeClasspath'.
   > Failed to transform classes.jar (project :path_provider_android) to match attributes {artifactType=android-dex, asm-transformed-variant=NONE, com.android.build.api.attributes.AgpVersionAttr=7.3.0, com.android.build.api.attributes.BuildTypeAttr=debug, com.android.build.gradle.internal.attributes.VariantAttr=debug, dexing-enable-desugaring=true, dexing-enable-jacoco-instrumentation=false, dexing-is-debuggable=true, dexing-min-sdk=21, org.gradle.libraryelements=jar, org.gradle.usage=java-runtime}.
      > Execution failed for DexingWithClasspathTransform: /home/ajthapa/dev/projects/flutter/MyAppName/00__Play_Store_builds/00__Closed_Test_version/update__feature_tests/MyAppName_v1.0.29__without_Admob_Ads/nepali_unit_conv/build/path_provider_android/intermediates/runtime_library_classes_jar/debug/classes.jar.
         > Error while dexing.

* 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 4m 10s
Error: Gradle task assembleDebug failed with exit code 1

Exited (1).

环境信息（flutter doctor --verbose输出） #

[✓] Flutter (Channel stable, 3.27.2, on Ubuntu 24.04.1 LTS 6.8.0-51-generic, locale en_GB.UTF-8)
    • Flutter version 3.27.2 on channel stable at /home/ajthapa/dev/tooling/flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 68415ad1d9 (4 days ago), 2025-01-13 10:22:03 -0800
    • Engine revision e672b006cb
    • Dart version 3.6.1
    • DevTools version 2.40.2

[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.1)
    • Android SDK at /home/ajthapa/Android/Sdk
    • Platform android-35, build-tools 35.0.1
    • Java binary at: /home/ajthapa/dev/tooling/android-studio/jbr/bin/java
    • Java version OpenJDK Runtime Environment (build 21.0.4+-12422083-b607.1)
    • All Android licenses accepted.

[✓] Chrome - develop for the web
    • Chrome at google-chrome

[✓] Linux toolchain - develop for Linux desktop
    • Ubuntu clang version 18.1.3 (1ubuntu1)
    • cmake version 3.28.3
    • ninja version 1.11.1
    • pkg-config version 1.8.1

[✓] Android Studio (version 2024.2)
    • Android Studio at /home/ajthapa/dev/tooling/android-studio
    • Flutter plugin version 83.0.3
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 21.0.4+-12422083-b607.1)

[✓] VS Code (version 1.96.4)
    • VS Code at /usr/share/code
    • Flutter extension version 3.102.0

[✓] Connected device (3 available)
    • sdk gphone64 x86 64 (mobile) • emulator-5554 • android-x64    • Android 15 (API 35) (emulator)
    • Linux (desktop)              • linux         • linux-x64      • Ubuntu 24.04.1 LTS 6.8.0-51-generic
    • Chrome (web)                 • chrome        • web-javascript • Google Chrome 131.0.6778.204

[✓] Network resources
    • All expected network resources are available.

• No issues found!

解决方案步骤 #

1. 统一Gradle与AGP版本 #

当前使用Gradle 8.5，但AGP版本仍为7.3.0，两者不兼容。修改项目android/build.gradle中的AGP版本为适配Gradle 8.5的版本（如8.2.0及以上）：

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.0' // 替换为对应兼容版本
    }
}

2. 清理Gradle缓存 #

执行以下命令彻底清理旧缓存：

./gradlew clean
./gradlew build --no-build-cache
rm -rf ~/.gradle/caches

3. 配置Java Toolchain指定版本 #

在项目android/app/build.gradle中添加Java版本配置，确保与Gradle/AGP兼容：

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = '17'
    }
    // 强制指定Java工具链版本
    java {
        toolchain {
            languageVersion = JavaLanguageVersion.of(17)
        }
    }
}

若坚持使用Java 21，需确保AGP版本在8.3+，并验证所有插件支持Java 21。

4. 更新Flutter依赖插件 #

运行命令更新所有依赖，尤其是出现错误的path_provider_android插件：

flutter pub upgrade

5. 匹配Build Tools与AGP版本 #

确保Build Tools版本与AGP兼容，在android/app/build.gradle中指定与当前SDK匹配的版本：

android {
    buildToolsVersion "35.0.1" // 与SDK版本一致
}

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