Flutter 迁移声明式 Gradle 插件

链接

原文：https://docs.flutter.dev/release/breaking-changes/flutter-gradle-plugin-apply
Issue：https://github.com/flutter/flutter/issues/135392

摘要

要构建 Android 上的 Flutter 应用程序，必须应用 Flutter 的 Gradle 插件。在历史上，这是通过Gradle的传统、命令式应用脚本方法完成的。

在 Flutter 3.16 中，添加了对使用 Gradle 的 声明式插件 {} 块（也称为Plugin DSL）应用这些插件的支持，现在是推荐的方法。自 Flutter 3.16 以来，使用 flutter create 生成的项目使用 Plugin DSL 来应用 Gradle 插件。在 Flutter 3.16 之前创建的项目需要手动迁移。

使用 plugins {} 块应用 Gradle 插件将执行与以前相同的代码，应该产生相同的应用程序二进制文件。

要了解新的 Plugin DSL 语法相对于旧的 apply 脚本语法的优势，请参阅 Gradle文档。

将应用生态系统迁移到新方法也将使 Flutter 团队更容易开发 Flutter 的 Gradle 插件，并在未来启用令人兴奋的新功能，例如在 Gradle 构建脚本中使用 Kotlin 而不是 Groovy。

迁移

android/settings.gradle

将 <app-src>/android/settings.gradle 的内容替换为以下内容，记得用之前使用的值替换 {agpVersion} 和 {kotlinVersion}：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
pluginManagement {
    def flutterSdkPath = {
        def properties = new Properties()
        file("local.properties").withInputStream { properties.load(it) }
        def flutterSdkPath = properties.getProperty("flutter.sdk")
        assert flutterSdkPath != null, "local.properties中未设置flutter.sdk"
        return flutterSdkPath
    }
    settings.ext.flutterSdkPath = flutterSdkPath()

    includeBuild("${settings.ext.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
    id "org.jetbrains.kotlin.android" version "{kotlinVersion}" apply false
}

include ":app"

如果对这个文件进行了一些更改，请确保它们放在 pluginManagement {} 和 plugins {} 块之后，因为 Gradle 强制要求在这些块之前不得放置其他代码。

android/build.gradle

从 <app-src/android/build.gradle 中删除整个 buildscript 块：

1
2
3
4
5
6
7
8
9
10
11
-buildscript {
-    ext.kotlin_version = '{kotlinVersion}'
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-    }
-}

文件最终可能如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.buildDir = '../build'
subprojects {
    project.buildDir = "${rootProject.buildDir}/${project.name}"
}
subprojects {
    project.evaluationDependsOn(':app')
}

tasks.register("clean", Delete) {
    delete rootProject.buildDir
}

android/app/build.gradle

大多数更改必须在 <app-src>/android/app/build.gradle 中进行。首先，删除使用传统命令式应用方法的这两个代码块：

1
2
3
4
-def flutterRoot = localProperties.getProperty('flutter.sdk')
-if (flutterRoot == null) {
-    throw new GradleException("Flutter SDK未找到。在local.properties文件中定义位置 flutter.sdk。")
-}
1
2
3
-apply plugin: 'com.android.application'
-apply plugin: 'kotlin-android'
-apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"

现在再次应用插件，但这次使用Plugin DSL语法。在文件的顶部添加：

1
2
3
4
5
+plugins {
+    id "com.android.application"
+    id "kotlin-android"
+    id "dev.flutter.flutter-gradle-plugin"
+}

验证

执行 flutter run 以确认你的应用在连接的Android设备或模拟器上构建并启动。

例子

Google 移动服务和 Crashlytics

如果你的应用使用了 Google 移动服务和 Crashlytics，请从 <app-src>/android/build.gradle 中删除以下行：

1
2
3
4
5
6
7
8
9
 buildscript {
     // ...

     dependencies {
         // ...
-        classpath "com.google.gms:google-services:4.4.0"
-        classpath "com.google.firebase:firebase-crashlytics-gradle:2.9.9"
     }
 }

并从 <app-src>/android/app/build.gradle 中删除这两行：

1
2
-apply plugin: 'com.google.gms.google-services'
-apply plugin: 'com.google.firebase.crashlytics'

要迁移到 GMS 和 Crashlytics 插件的新的声明式应用，将以下行添加到 <app-src>/android/settings.gradle：

1
2
3
4
5
6
7
 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
+    id "com.google.gms.google-services" version "4.4.0" apply false
+    id "com.google.firebase.crashlytics" version "2.9.9" apply false
 }

并将以下行添加到 <app-src>/android/app/build.gradle：

1
2
3
4
5
6
7
 plugins {
     id "com.android.application"
     id "dev.flutter.flutter-gradle-plugin"
     id "org.jetbrains.kotlin.android"
+    id "com.google.gms.google-services"
+    id "com.google.firebase.crashlytics"
 }

时间轴

在稳定版本中的支持：3.16.0
在稳定版本中的推荐：3.19.0

参考