Flutter 项目 Gradle 版本更新指南

当 Flutter 项目无法构建 APK 文件，提示 Gradle 版本与 Kotlin Gradle 插件不兼容时（如 "The current Gradle version 4.10.2 is not compatible with the Kotlin Gradle plugin"），通常需要更新项目中的 Gradle 配置。

问题原因

Flutter 项目中的 Gradle 版本与 Kotlin 插件版本不匹配，通常是由于：

• 项目创建时间较早，使用的 Gradle 版本已过时
• 第三方插件（如 audioplayers）需要更高版本的 Gradle 支持
• Android 构建工具版本与 Gradle 版本不兼容

解决方案

方法一：使用 Android Studio 自动更新（推荐）

适用场景

适用于使用 Android Studio 进行开发的用户，操作简单且可自动处理兼容性问题。

1. 在 Flutter 项目中右键点击 android 文件夹
2. 选择 "Flutter" → "Open Android module in Android Studio"
3. 等待 Android Studio 完全加载项目
4. 如果右下角出现 Gradle 更新提示，点击 "Update" 或 "Yes"
5. 同步完成后，关闭 Android Studio 中的 Android 项目窗口
6. 返回 Flutter 项目，执行清理和重建：

flutter clean
flutter pub get

提示

如果 Android Studio 没有自动提示更新，可以手动检查：

• 菜单栏选择 File → Project Structure → Project
• 更新 "Android Gradle Plugin Version" 和 "Gradle Version"

方法二：命令行手动更新

适用场景

适合喜欢命令行操作或需要精确控制版本的用户。

1. 进入项目的 Android 目录：

cd android

2. 使用 Gradle Wrapper 更新到指定版本（以 7.6.1 为例）：

# Windows
gradlew wrapper --gradle-version=7.6.1

# macOS/Linux
./gradlew wrapper --gradle-version=7.6.1

3. 此命令会自动更新 gradle-wrapper.properties 文件中的 distributionUrl

方法三：完整配置文件更新

如果需要手动更新所有相关配置，请修改以下文件：

1. android/gradle/wrapper/gradle-wrapper.properties

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

2. android/build.gradle

buildscript {
    ext.kotlin_version = '1.7.10' // 更新 Kotlin 版本
    repositories {
        google()
        jcenter()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2' // 更新 Android Gradle 插件
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

3. android/app/build.gradle

android {
    compileSdkVersion 33 // 更新编译 SDK 版本
    
    defaultConfig {
        minSdkVersion 21  // 最低支持版本
        targetSdkVersion 33 // 目标 SDK 版本
        // ... 其他配置
    }
    // ... 其他配置
}

方法四：重新创建 Android 项目

注意事项

此方法会重置所有 Android 端的自定义配置（如应用图标、权限设置等），请先备份重要文件。

如果项目结构过于陈旧，最简单的解决方案是重新创建 Android 项目：

1. 备份 android 文件夹（特别是 key.properties 和签名配置）
2. 删除 android 文件夹
3. 在项目根目录运行：

flutter create .

4. 恢复之前备份的自定义配置

版本兼容性参考

当前推荐的版本组合（2024年更新）：

组件	推荐版本
Gradle	7.6.1
Android Gradle 插件	7.4.2
Kotlin	1.7.10+
编译 SDK	33+
目标 SDK	33+

查看 Gradle 与 Java 版本兼容性

Gradle 版本与 Java 版本存在兼容性要求，请参考 Gradle 官方兼容性矩阵确保环境正确配置。

常见问题排查

1. Java 版本问题：

   • 确保安装了与 Gradle 版本兼容的 Java 版本
   • 可以通过设置 org.gradle.java.home 指定 Java 路径

2. 插件兼容性：

   • 更新所有第三方插件到最新版本
   • 检查插件是否支持新的 Gradle 版本

3. 缓存问题：

   • 执行 flutter clean 和 flutter pub cache clean 清理缓存
   • 删除 android/.gradle 文件夹强制重新下载依赖

总结

更新 Flutter 项目中的 Gradle 版本是维护旧项目的常见任务。推荐使用 Android Studio 的自动更新功能，或者通过命令行使用 Gradle Wrapper 进行更新。保持 Gradle 和相关组件的最新版本可以获得更好的性能和安全性，同时避免构建兼容性问题。

最佳实践

• 定期检查并更新 Gradle 和相关依赖
• 创建新项目时记录使用的版本号，便于后续维护
• 使用版本控制跟踪 Gradle 配置的变更

通过上述方法，您应该能够解决 Flutter 项目中的 Gradle 版本兼容性问题，顺利完成 APK 构建。