Flutter 3.19.2 中 Kotlin 版本的配置方法

问题描述

在 Flutter 3.16 及以上版本中，官方移除了 /android/build.gradle 文件中的 buildscript 配置块。更新到 Flutter 3.19.2 后，开发者在使用 ext.kotlin_version 指定 Kotlin 版本时会出现问题。此时项目中会出现类似错误提示：

Flutter version 3.19.2 requires a newer version of the Kotlin Gradle plugin.

根本原因是 Flutter 3.16+ 改用了 Gradle 的声明式插件应用方式（Plugin DSL），不再支持旧版 buildscript 配置方式。若在 build.gradle 中继续使用 ext.kotlin_version 变量将导致 Kotlin 版本配置失效。

解决方案

关键配置位置

在 Flutter 3.16+ 中，Kotlin 版本需在 android/settings.gradle（或 settings.gradle.kts）文件中配置，具体位置在 plugins 代码块内。

pluginManagement {
    // 其他配置...
}

plugins {
    // 其他插件...
    id "org.jetbrains.kotlin.android" version "2.1.10" apply false
}

include ":app"

快速修复步骤

1. 打开 android/settings.gradle 文件
2. 在 plugins 块中找到包含 org.jetbrains.kotlin.android 的行
3. 将版本号更新为最新的 Kotlin 版本
4. 移除 /android/build.gradle 中所有与 kotlin_version 相关的剩余代码

获取官方最新版本

访问 Kotlin 官方发布页面 查询当前最新版本，替换上述配置中的 2.1.10

完整示例配置

pluginManagement {
    def flutterSdkPath = {
        def properties = new Properties()
        file("local.properties").withInputStream { properties.load(it) }
        def flutterSdkPath = properties.getProperty("flutter.sdk")
        assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
        return flutterSdkPath
    }()
    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")
    
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.1.2" apply false
    id "org.jetbrains.kotlin.android" version "2.1.10" apply false  // 修改此行版本号
}

include ":app"

迁移旧项目的完整流程

如果是从 Flutter 3.16 之前版本升级的项目，需要完整迁移配置：

1. 更新 settings.gradle

替换 android/settings.gradle 为以下结构（保留原有自定义配置）：

pluginManagement {
    // ... (保持原有 pluginManagement 内容)
}

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "{agpVersion}" apply false
    id "org.jetbrains.kotlin.android" version "{kotlinVersion}" apply false
}

include ":app"

2. 清理 build.gradle

删除 /android/build.gradle 中整个 buildscript 块：

- buildscript {
-     ext.kotlin_version = '{kotlinVersion}'
-     repositories {
-         google()
-         mavenCentral()
-     }
-     
-     dependencies {
-         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-     }
- }

3. 更新 app/build.gradle

在 android/app/build.gradle 文件顶部添加插件声明：

plugins {
    id "com.android.application"
    id "kotlin-android"
    id "dev.flutter.flutter-gradle-plugin"
}

4. 清理缓存

执行以下终端命令清理构建缓存：

flutter clean
cd android
./gradlew cleanBuildCache

Windows 环境注意

如果缓存清理不彻底，手动删除：

1. 按 Win + R 输入 resmon
2. 在"关联的句柄"中搜索 gradle
3. 结束所有占用 gradle/caches 的 java.exe 进程
4. 删除 %USERPROFILE%/.gradle/caches 文件夹

常见问题解决

发布 APK 时仍报错

在 /android/build.gradle 的 subprojects 块中添加 Android 版本配置：

subprojects {
    afterEvaluate { project ->
        if (project.plugins.hasPlugin("com.android.application") ||
                project.plugins.hasPlugin("com.android.library")) {
            project.android {
                compileSdkVersion 34
                buildToolsVersion "34.0.0"
            }
        }
    }
}

配置后无法同步 Gradle

1. 检查 Kotlin 版本拼写是否正确
2. 确认所有配置块开头无多余字符（Gradle 要求 pluginManagement 和 plugins 必须位于文件开头）
3. 对比使用 flutter create 生成的全新项目配置
4. 执行 flutter upgrade 确保使用最新 Flutter 版本

参考官方迁移文档：Flutter Gradle Plugin 应用方式变更