Flutter Gradle 插件迁移指南：废弃 apply 方法问题解决

问题描述

升级 Flutter 到 3.19.0+ 后，编译时出现以下警告提示：

You are applying Flutter's app_plugin_loader Gradle plugin
imperatively using the apply script method, which is deprecated and
will be removed in a future release. Migrate to applying Gradle
plugins with the declarative plugins block...

核心问题：从 Flutter 3.16 开始，官方废弃了传统的 Gradle 插件声明方式（apply脚本方法），改用声明式 DSL 语法。如不及时迁移，后续版本将无法编译。

根本原因变化

旧版 (Flutter ❤️.16)	新版 (Flutter ≥3.16)
命令式 apply 脚本	声明式 plugins 块
集中式 buildscript 配置	分布式 plugins 管理
手动加载 flutter.gradle	自动插件加载机制

解决方案

🛠️ 推荐方案：手动迁移（保留自定义配置）

修改以下三个文件完成迁移：

步骤 1：修改 android/settings.gradle

替换整个文件内容（注意替换 {agpVersion} 和 {kotlinVersion}）：

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 "{agpVersion}" apply false  // 替换为您的AGP版本
    id "org.jetbrains.kotlin.android" version "{kotlinVersion}" apply false  // 替换为Kotlin版本
}

include ":app"

版本查找方法

1. 打开 android/build.gradle（旧位置）
2. 查找 classpath 'com.android.tools.build:gradle:x.x.x' → x.x.x 即 AGP 版本
3. 查找 ext.kotlin_version = 'x.x.x' → x.x.x 即 Kotlin 版本

步骤 2：修改 android/build.gradle

移除整个 buildscript 块，保留其他内容：

// DELETE THIS ENTIRE BLOCK ▼
buildscript {
    ext.kotlin_version = '1.7.10'
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.3.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}
// ▲ DELETE UNTIL HERE

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

// ...保留文件其他部分...

步骤 3：修改 android/app/build.gradle

新增顶部 plugins 块：

// 新增此代码块 ▼
plugins {
    id "com.android.application"
    id "kotlin-android"
    id "dev.flutter.flutter-gradle-plugin"
}
// ▲ 新增结束

删除旧代码

删除以下代码片段：

// 删除以下代码 ▼
def flutterRoot = localProperties.getProperty('flutter.sdk')
if (flutterRoot == null) {
    throw new GradleException("Flutter SDK not found...")
}

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"
// ▲ 删除结束

移除过时依赖：

dependencies {
    // 删除此行 (Flutter 3.22+必需)
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version" ❌
}

步骤 4：处理第三方插件（如 Firebase）

迁移 GMS/Crashlytics 等插件：

// android/app/build.gradle 新增
plugins {
    // ...其他插件...
    id "com.google.gms.google-services"        // GMS 插件
    id "com.google.firebase.crashlytics"       // Crashlytics
}

// android/settings.gradle 新增
plugins {
    // ...其他插件...
    id "com.google.gms.google-services" version "4.4.0" apply false
    id "com.google.firebase.crashlytics" version "2.9.9" apply false
}

⚡ 备选方案：重新生成 Android 项目（适合新项目）

适用于无自定义配置的项目（操作前务必备份）：

rm -rf android/             # 删除 android 目录
flutter create . --platforms=android  # 仅生成 Android 平台

操作风险

1. 会丢失所有原生端自定义配置（权限/图标等）
2. 建议使用 Git 管理，迁移后对比文件差异：

git restore --staged android   # 恢复受保护文件
git restore android            # 保留修改

验证与调试

完成迁移后执行：

flutter clean    # 清理缓存
flutter run      # 重新编译

若遇到问题：

1. 确认所有版本号匹配（AGP/Kotlin）
2. 检查 " 和 ' 符号是否统一（推荐使用双引号）
3. 参考官方迁移指南：Flutter 文档

版本兼容说明

Flutter 版本	操作建议
< 3.16	无需立即操作
3.16-3.19	需迁移（显示警告）
≥ 3.22	必须迁移（否则编译失败）

最佳实践：建议在升级 Flutter 后，优先完成此迁移以避免未来兼容性问题。