跳到主內容

概述

#

要構建 Flutter Android 應用，必須應用 Flutter 的 Gradle 外掛。過去，這通常透過 Gradle 的 舊式命令式 apply 指令碼方法 以命令式的方式完成。

在 Flutter 3.16 中，已新增對使用 Gradle 的 宣告式 plugins {} 塊（也稱為 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

#

首先，找到專案當前使用的 Android Gradle Plugin (AGP) 和 Kotlin 的版本。除非它們已被移動，否則它們很可能定義在 <app-src>/android/build.gradle 檔案的 buildscript 塊中。例如，考慮此更改之前使用新 Flutter 應用建立的 build.gradle 檔案

groovy
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"
    }
}

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
}

AGP 版本是行 classpath 'com.android.tools.build:gradle:7.3.0' 末尾的數字，在本例中為 7.3.0。同樣，Kotlin 版本在行 ext.kotlin_version = '1.7.10' 的末尾，在本例中為 1.7.10。

接下來，用以下內容替換 <app-src>/android/settings.gradle 的內容，記住用先前確定的值替換 {agpVersion} 和 {kotlinVersion}

groovy
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" // apply true
    id "com.android.application" version "{agpVersion}" apply false
    id "org.jetbrains.kotlin.android" version "{kotlinVersion}" apply false
}

include ":app"

如果您對此檔案進行了一些更改，請確保它們位於 pluginManagement {} 和 plugins {} 塊之後，因為 Gradle 會強制要求這些塊之前不能放置任何其他程式碼。

Flutter Gradle 外掛 (dev.flutter.flutter-plugin-loader) 不應設定為 apply false（預設值為 true），或者應明確設定為 true。

android/build.gradle

#

從 <app-src/android/build.gradle 中刪除整個 buildscript 塊

groovy
buildscript {
    ext.kotlin_version = '{kotlinVersion}'
    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:gradle-plugin:$kotlin_version"
    }
}

該檔案最終可能如下所示

groovy
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 中的程式碼也需要進行以下更改。首先，刪除以下兩個使用舊式命令式 apply 方法的程式碼塊

groovy
def flutterRoot = localProperties.getProperty('flutter.sdk')
if (flutterRoot == null) {
    throw new GradleException("Flutter SDK not found. Define location with flutter.sdk in the local.properties file.")
}
groovy
apply plugin: 'com.android.application'
apply plugin: 'com.jetbrains.kotlin.android'
apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"

現在再次應用外掛，但這次使用 Plugin DSL 語法。在檔案的最頂部新增

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

"dev.flutter.flutter-gradle-plugin" 是專案 Flutter Gradle 外掛，它與在 settings.gradle(.kts) 中應用的字串（"dev.flutter.flutter-plugin-loader"）不同。

最後，如果您的 dependencies 塊包含對 "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version" 的依賴，請刪除該依賴。

groovy
dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
}

如果這是 dependencies 塊中的唯一依賴項，則可以完全刪除該塊。

驗證

#

執行 flutter run 以確認您的應用在連線的 Android 裝置或模擬器上能夠成功構建和啟動。

示例

#

Google Mobile Services 和 Crashlytics

#

如果您的應用使用了 Google Mobile Services 和 Crashlytics，請從 <app-src>/android/build.gradle 中刪除以下行

groovy
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 中刪除這兩行

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

要遷移到 GMS 和 Crashlytics 外掛的新宣告式 apply 語法，請將它們新增到應用 <app-src>/android/settings.gradle 檔案的 plugins 塊中。新增的內容應與以下內容類似，但使用您期望的版本，可能與您從 <app-src>/android/build.gradle 檔案中刪除的版本匹配。

groovy
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

groovy
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

參考資料

#

flutter create 生成的 Gradle 構建檔案在不同 Flutter 版本之間存在差異。有關詳細概述，請參閱 issue #135392。您應該考慮使用最新的構建檔案版本。

除非另有說明，本網站上的文件反映了 Flutter 的最新穩定版本。頁面最後更新於 2025-04-28。 檢視原始碼 或 報告問題。