Flutter 项目 Kotlin Gradle 插件版本过低问题解决

2025-03-12 23:35:56

Flutter 项目中 Kotlin Gradle 插件版本过低问题的解决办法

开发 Flutter 项目时，构建 release APK 或运行 Gradle 的 assembleRelease 任务，有时会碰到类似下面的错误：

FAILURE: Build failed with an exception.

* What went wrong: 
Execution failed for task ':app:compileReleaseKotlin'.
> A failure occurred while executing org.jetbrains.kotlin.compilerRunner.GradleCompilerRunnerWithWorkers$GradleKotlinCompilerWorkAction Compilation error. See log for more details

...

[!] Your project requires a newer version of the Kotlin Gradle plugin.
...

简单来说，就是你的项目需要的 Kotlin Gradle 插件版本太旧了，需要升级。

问题原因

Flutter 项目构建过程中，会用到 Gradle 和 Kotlin Gradle 插件。如果你的项目所依赖的库（比如一些 Flutter 插件），或者 Flutter SDK 本身，要求一个较高版本的 Kotlin Gradle 插件，而你项目里配置的版本较低，就会导致这个构建错误。这一般出现在你升级了 Flutter SDK 或者某些第三方依赖后。

解决办法

解决这问题，核心就是升级 Kotlin Gradle 插件版本。具体有以下几种操作方式：

1. 直接修改 `android/build.gradle` 文件 (推荐)

这是最常用也最直接的办法。打开你 Flutter 项目下的 android/build.gradle 文件。找到 ext.kotlin_version = '...' 这一行（可能不存在，如果不存在就自己手动加上这行），然后把版本号改成一个较新的版本。

操作步骤：

打开 android/build.gradle 文件。

找到或添加 ext.kotlin_version 变量：

buildscript {
    ext.kotlin_version = '1.9.10' // 把这里改成较新的版本！
    repositories {
        google()
        mavenCentral()
    }
...

到 Kotlin 官方发布页面找一个较新的、稳定的版本号。比如写这篇文章时，你可以选择 1.9.10 或者 1.9.22，具体看情况而定。原则是选择相对新, 且稳定的版本. 不要选太超前的版本，可能会有兼容性问题.
修改完后，保存文件。

清理并重新构建项目

flutter clean
flutter pub get
cd android
./gradlew clean
cd ..
flutter build apk --release # 或者 flutter build appbundle --release

原理： android/build.gradle 文件是整个 Android 项目的构建脚本。ext.kotlin_version 定义了 Kotlin Gradle 插件的版本。Gradle 在构建时，会根据这个变量去下载对应版本的插件。

2. 修改 `android/settings.gradle` 文件

如果你的Flutter项目较新,可能插件配置不在 android/build.gradle , 而是放在了android/settings.gradle中,具体错误信息里会有提示. 这种情况修改android/settings.gradle.

操作步骤:

打开 android/settings.gradle 文件。

在 plugins 块中找到 id "org.jetbrains.kotlin.android":

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.2.2" apply false
    id "org.jetbrains.kotlin.android" version "1.9.10" apply false //修改这里
}

把 version 后面的版本号改一个较新的版本 (去Kotlin 官方网站查)。
保存, 清理, 并重新构建项目(参考上面步骤5).

原理: 和方法一类似, 不过新的 Flutter 项目,插件信息会更多地放到 settings.gradle. 修改的还是 Kotlin Gradle 插件的版本。

3. 如果使用了自定义的 Gradle 插件

如果你的项目里，有些特殊的构建逻辑，定义了自己 Gradle 插件（这种情况相对少见），并且这些插件依赖了 Kotlin，那你可能需要在这些插件的 build.gradle 或 build.gradle.kts 里，修改 Kotlin 依赖的版本。

操作步骤 (假设你知道自己有自定义插件)：

找到你的自定义 Gradle 插件的代码目录。
打开插件的 build.gradle (如果是 Kotlin DSL, 就是 build.gradle.kts)。

找到类似下面的依赖配置：

// build.gradle (Groovy)
dependencies {
    implementation "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.10" // 改这里
    // ... 其他依赖
}

或者

// build.gradle.kts (Kotlin DSL)
dependencies {
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.10") // 改这里
    // ... 其他依赖
}

更新版本号，保存，清理构建。

原理: 自定义插件, 通常也需要配置依赖. 如果你的自定义插件也使用了Kotlin, 同样要保证版本和项目兼容.

进阶：版本选择与兼容性

版本号的选择： 不要盲目追求最新。可以优先考虑和你的 Flutter SDK 版本配套的 Kotlin 版本。Flutter 官方文档或 release notes 有时会提到建议的 Kotlin 版本。实在不清楚,就选相对新，又经过一定时间验证的稳定版本。
多个地方定义版本？ 确保 android/build.gradle、android/settings.gradle，还有可能存在的自定义 Gradle 插件里，Kotlin Gradle 插件的版本保持一致！避免出现冲突。
渐进式升级： 如果你的项目比较老，一下子升级到最新的 Kotlin 版本可能不兼容。可以尝试小步快跑，一次升一个小版本，然后测试，看看有没有问题，再继续升。
gradle.properties的使用(可选) : 如果你希望更好的管理多个项目的Kotlin版本，可以将kotlin.version写到gradle.properties 文件中，然后在build.gradle 文件和 setting.gradle 中引用它。
1. 在android/gradle.properties中定义
```
kotlin.version=1.9.10
```
2. 在build.gradle中使用：
```
 ext.kotlin_version = properties['kotlin.version'] as String
```
```
3. 在 `settings.gradle`中使用

   ```gradle
    id "org.jetbrains.kotlin.android" version properties['kotlin.version'] apply false
   ```
```
清理缓存 ：如果修改了版本，但构建还是有问题。可以尝试清理一下 Gradle 的缓存。找到 Gradle 的用户主目录（通常是 ~/.gradle/caches），删除里面的内容（谨慎操作! 最好先备份. 或者删除特定版本下的缓存）。
更安全的是执行命令:
```
./gradlew cleanBuildCache
```

安全建议

备份！ 在做任何修改之前，备份你的 android/build.gradle、android/settings.gradle 或相关文件。改出问题了好回退。
提交代码！ 改之前，或者改完后，记得把代码提交到版本控制系统（比如 Git）。
注意更新日志: 更新第三方库或者 Flutter SDK的时候，留意一下版本更新日志。很多时候,版本要求变更会在更新日志中说明。

希望上面内容可以帮你处理掉 “Your project requires a newer version of the Kotlin Gradle plugin” 报错。