Flutter构建失败：Android Gradle Plugin(AGP)版本冲突问题

问题背景 #

开发Flutter项目时，为解决Java 8过时警告，将compileOptions和kotlinOptions切换到Java 11后，出现AGP版本冲突：Gradle提示com.android.application插件8.2.1无法解析，因为类路径中已存在8.1.0版本。即使更新了android/build.gradle和android/app/build.gradle中的AGP版本，清理项目后问题依然存在。

错误日志：

FAILURE: Build failed with an exception.

* Where:
Build file '/Users/jaydedaniya/Documents/FlutterProject/CompassPro-Gitlab/android/app/build.gradle' line: 2

* What went wrong:
Error resolving plugin [id: 'com.android.application', version: '8.2.1']
> The request for this plugin could not be satisfied because the plugin is already on the classpath with a different version (8.1.0).

BUILD FAILED in 31s
Error: Gradle task assembleDebug failed with exit code 1

问题原因分析 #

1. AGP引入方式冲突：同时使用buildscript的classpath和plugins DSL两种方式配置AGP，Gradle版本解析逻辑冲突，导致旧版本残留。
2. 第三方插件依赖旧版AGP：项目依赖的某个Flutter插件内部硬编码了AGP 8.1.0版本，强制引入到类路径中。
3. Gradle缓存未彻底清理：项目或全局Gradle缓存中仍保留了AGP 8.1.0的文件，Gradle优先加载缓存内容。

解决方案 #

1. 统一AGP引入方式 #

不要同时混用buildscript和plugins DSL，二选一即可：

方式A：使用Plugins DSL（推荐）

• 删除android/build.gradle中buildscript块内的AGP classpath配置；
• 修改android/app/build.gradle的plugins块：

plugins {
    id "com.android.application" version "8.2.1" apply true
    id "kotlin-android" version "1.9.20" apply true
    id "dev.flutter.flutter-gradle-plugin" version "1.0.0" apply true
}

• （可选）在settings.gradle中统一管理插件版本，避免分散配置：

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 "com.android.application" version "8.2.1"
        id "com.android.library" version "8.2.1"
        id "kotlin-android" version "1.9.20"
        id "dev.flutter.flutter-gradle-plugin" version "1.0.0"
    }
}

方式B：使用Buildscript

• 删除android/app/build.gradle中plugins块内的AGP版本配置，改为应用插件：

apply plugin: "com.android.application"
apply plugin: "kotlin-android"
apply plugin: "dev.flutter.flutter-gradle-plugin"

• 确保android/build.gradle的buildscript块中AGP版本统一为8.2.1：

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

    dependencies {
        classpath "com.android.tools.build:gradle:8.2.1"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

2. 排查第三方插件依赖冲突 #

运行以下命令查看项目依赖树，定位引入AGP 8.1.0的插件：

./gradlew android:dependencies

或者用Flutter命令：

flutter pub deps --style=compact

• 若找到对应插件，优先升级该插件到兼容AGP 8.2.1的版本；
• 若无法升级插件，在android/build.gradle中强制统一AGP版本：

configurations.all {
    resolutionStrategy {
        force "com.android.tools.build:gradle:8.2.1"
    }
}

3. 彻底清理Gradle缓存 #

除了常规的flutter clean，还需清理项目和全局Gradle缓存：

# 清理Flutter项目缓存
flutter clean
# 删除项目本地Gradle缓存
rm -rf android/.gradle
# 删除全局Gradle缓存（macOS/Linux）
rm -rf ~/.gradle/caches
# Windows用户执行：
# rmdir /s /q %USERPROFILE%\.gradle\caches

清理完成后重新执行：

flutter pub get
flutter run

4. 验证Gradle版本兼容性 #

AGP 8.2.1要求Gradle版本为8.3，确认gradle-wrapper.properties配置正确：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip

疑问解答 #

为何更新至8.2.1后，Gradle仍检测到AGP 8.1.0版本？ #

• 核心原因是AGP引入方式冲突，两种配置方式导致版本解析逻辑混乱；
• 其次是第三方插件硬编码旧版本AGP，强制将8.1.0引入类路径；
• 最后可能是Gradle缓存未彻底清理，旧版本文件未被移除，Gradle优先加载缓存内容。

如何解决该版本冲突，成功构建Flutter项目？ #

按照上述步骤逐一排查：先统一AGP引入方式，再定位并处理第三方插件依赖，然后彻底清理缓存，最后验证Gradle版本兼容性，即可解决冲突。

内容的提问来源于stack exchange，提问作者Jay Dedaniya