Flutter 项目中的 Kotlin 版本更新问题

更新时间

本文内容更新于 2025 年 5 月，适用于当前最新的 Flutter 和 Kotlin 版本

当你升级 Flutter 项目到空安全版本后，经常会遇到 "Your project requires a newer version of the Kotlin Gradle plugin" 错误。这个错误表明你的项目需要使用更新版本的 Kotlin Gradle 插件来兼容新的特性。

问题原因

Flutter 项目中的 Android 部分使用 Kotlin 作为开发语言，当 Flutter SDK 升级后，对应的 Kotlin 版本也需要同步更新。错误信息通常如下所示：

BUILD FAILED in 8s
[!] Your project requires a newer version of the Kotlin Gradle plugin.
    Find the latest version on https://kotlinlang.org/docs/gradle.html#plugin-and-versions

解决方案

方法一：更新 settings.gradle 文件（推荐）

对于使用 Flutter 3.19 及以上版本创建的项目，需要修改 android/settings.gradle 文件：

pluginManagement {
    // ... 其他配置 ...
    
    plugins {
        id "dev.flutter.flutter-gradle-plugin" version "1.0.0" apply false
        id "com.android.application" version "8.1.0" apply false
        id "org.jetbrains.kotlin.android" version "2.1.10" apply false // 更新此行
    }
}

方法二：更新 build.gradle 文件

对于较旧版本的 Flutter 项目，需要修改 android/build.gradle 文件：

buildscript {
    ext.kotlin_version = '2.1.10' // 更新此版本号
    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:8.1.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

方法三：同时更新多处配置

某些情况下可能需要同时更新多个文件：

1. android/settings.gradle:

plugins {
    id "org.jetbrains.kotlin.android" version "2.1.10" apply false
}

2. android/app/build.gradle:

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.1.10"
    // 其他依赖...
}

获取最新版本号

要获取最新的 Kotlin 版本号，请访问：

• Kotlin 官方发布页面
• Gradle 插件配置文档

当前版本信息

截至 2025 年 5 月，Kotlin 最新稳定版本为 2.1.10，建议始终使用官方推荐的最新稳定版本。

清理和重建

更新版本后，执行以下命令确保更改生效：

flutter clean
flutter pub get

常见问题排查

1. 文件锁定问题（Windows）

如果在 Windows 上遇到文件删除错误，可能是 OpenJDK 进程锁定了文件：

# 错误示例：无法删除目录中的APK文件
FAILURE: Build failed with an exception.
> java.io.IOException: Unable to delete directory

解决方案：通过任务管理器终止 OpenJDK Platform binary 进程，然后重新构建。

2. 多位置版本不一致

确保所有文件中的 Kotlin 版本号一致，避免出现版本冲突。

3. Gradle 版本兼容性

更新 Kotlin 版本时，也需要确保 Gradle 版本兼容：

# gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip

替代方案

如果上述方法都无效，可以考虑重建 Android 模块：

# 备份后删除 android 文件夹
rm -rf android

# 重新生成 Android 项目
flutter create .

注意事项

• 重建前务必备份所有自定义配置
• 此方法会重置所有 Android 端的修改

总结

Kotlin 版本更新是 Flutter 项目维护中的常见操作。通过正确更新 settings.gradle 或 build.gradle 文件中的版本号，并执行清理重建命令，可以解决大多数版本兼容性问题。始终建议使用 Kotlin 官方推荐的最新稳定版本以确保最佳兼容性和性能。