Very Good CLI 项目中的 Gradle 版本兼容性问题解析

问题背景

在使用 Very Good CLI 创建 Flutter 项目时，开发者可能会遇到一个常见的构建错误："Unsupported class file major version 65"。这个错误通常发生在新建项目后尝试在 Android 设备上运行时。本文将深入分析这个问题的根源，并提供完整的解决方案。

错误原因分析

该问题的核心在于 Java 版本与 Gradle 版本之间的不兼容。具体表现为：

1. 新版本的 Android Studio 默认使用 Java 21
2. 但项目模板中配置的 Gradle 版本较旧（如 7.5）
3. 旧版 Gradle 无法处理 Java 21 生成的字节码（class file major version 65）

这种版本不匹配会导致构建过程中出现语义分析阶段的异常。

完整解决方案

要彻底解决这个问题，需要对项目进行多处配置调整：

1. 更新 Gradle 包装器版本

修改 android/gradle/wrapper/gradle-wrapper.properties 文件，将 distributionUrl 更新为：

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

2. 更新 Android 插件版本

在 android/settings.gradle 文件中，更新 Android 和 Kotlin 插件版本：

id "com.android.application" version "8.1.0" apply false
id "org.jetbrains.kotlin.android" version "1.8.22" apply false

3. 调整编译选项

在 android/app/build.gradle 文件中，确保编译选项正确配置：

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

kotlinOptions {
    jvmTarget = JavaVersion.VERSION_1_8
}

技术背景深入

这个问题的出现反映了 Flutter 生态系统中一个常见的挑战：工具链的版本协调。当 Android Studio、Java、Gradle 和 Flutter 工具链中的任何一个组件更新时，都可能引发类似的兼容性问题。

Java 的 class file major version 是一个重要的兼容性指标：

• Java 8 对应 major version 52
• Java 11 对应 major version 55
• Java 17 对应 major version 61
• Java 21 对应 major version 65

当 Gradle 版本无法识别较高的 major version 时，就会抛出本文讨论的错误。

项目维护状态

Very Good CLI 团队已经意识到这个问题，并在最新版本中更新了项目模板，确保新创建的项目使用兼容的版本组合。对于现有项目，开发者可以按照上述解决方案手动调整配置。

最佳实践建议

为了避免类似问题，建议开发者：

1. 定期检查并更新项目中的构建工具版本
2. 在升级开发环境（如 Android Studio）后，检查相关配置是否需要调整
3. 关注 Flutter 和 Gradle 的官方兼容性文档
4. 考虑使用版本管理工具确保团队成员的开发环境一致性

通过理解这些底层机制和采取预防措施，开发者可以更顺利地使用 Very Good CLI 创建和管理 Flutter 项目。