【Flutter Android 构建】Flutter / Gradle / AGP / Kotlin 版本对应关系全解析 - 2026版

西半球2026-06-18 8:32

【Flutter Android 构建】Flutter / Gradle / AGP / Kotlin 版本对应关系全解析 - 2026版

摘要 ：用 Flutter 打 Android 包时，flutter build apk 失败的很大一部分原因，是 android/ 目录里的 Gradle、AGP、Kotlin 版本没对齐。本文面向 Flutter 开发者，汇总构建链各组件的版本对应关系，并说明 Flutter SDK 版本 与 android/ 配置如何配合。

适用人群：Flutter 开发者、维护老 Flutter 项目的工程师、准备升级 AGP 9.x 的 Flutter 团队

数据来源：Flutter 官方文档 + Google / Gradle / Kotlin 官方文档（截至 2026 年 6 月）

建议收藏 ：升级前对照 第二节 2.1 完整对照表 和 第七节 7.2 三合一组合表。

写在前面：Flutter 开发者为什么也会踩版本坑？

你可能以为 Flutter 项目只要管好 Dart 就行，但执行 flutter build apk 时，底层走的仍是 android/ 里的 Gradle 构建链。常见报错：

text 复制代码 
Minimum supported Gradle version is 9.3.1. Current version is 8.13.
text 复制代码 
flutter build apk 失败，但 flutter run 可以
text 复制代码 
A problem occurred configuring project ':某插件'. 
> Could not resolve com.android.tools.build:gradle:x.x.x

一句话总结 ：Flutter 负责 Dart 层，android/ 目录负责 Android 打包层 ------两套版本都要对齐。而且 flutter upgrade 不会自动升级你项目里的 android/ 配置。

需要版本对齐的组件总览

组件 Flutter 项目里在哪 是否必须对齐 章节
Flutter SDK flutter --version 必须（决定模板默认值和支持范围） 第二节 2.1
Gradle ↔ AGP android/gradle/wrapper/ + android/settings.gradle(.kts) 必须 第三节
Kotlin (KGP) ↔ AGP android/settings.gradle(.kts) 或 android/build.gradle（老项目） 必须 第七节
Flutter Gradle Plugin Flutter SDK 内置，随 android/ 模板注入 随 Flutter 版本 第一节
Flutter 第三方插件 各插件的 android/build.gradle 升级时需逐个检查 第九节
compileSdk ↔ AGP android/app/build.gradle(.kts) 必须 第六节
JDK ↔ Gradle / AGP Studio 设置 / android/gradle.properties 必须 第七节 7.5
KSP ↔ KGP 用了带 KSP 的插件时 按需 第七节 7.3
Android Studio ↔ AGP IDE 版本 用 Android Studio 打开 android/ 时 第五节

一、Flutter 项目的 Android 构建是怎么运作的？

1.1 先用一张图看懂

text 复制代码 
  你写的 Dart 代码（lib/）
        |
  Flutter SDK（flutter build / flutter run）
        |
  android/ 目录  ← 本文重点，纯 Android 构建链
        |
   Flutter Gradle Plugin（连接 Flutter 引擎与 APK）
        |
       AGP          ← android/settings.gradle.kts
        |
     Gradle         ← android/gradle/wrapper/gradle-wrapper.properties
        |
       JDK          ← Studio 设置（版本见 2.1 表：8 / 11 / 17）

关键认知 ：Flutter 不是替代 AGP/Gradle，而是在它们之上加了一层 Flutter Gradle Plugin，把 Dart 编译产物和 Android 壳子打包在一起。

1.2 android/ 目录里要改哪些文件？

文件 管什么 适用版本
android/settings.gradle.kts AGP 版本、Kotlin 版本 3.29+ 新建项目默认
android/settings.gradle AGP 版本（Groovy DSL） 3.16 ~ 3.28 常见
android/build.gradle 根工程 AGP / Kotlin classpath 2.x ~ 3.10 老项目
android/gradle/wrapper/gradle-wrapper.properties Gradle 版本 全版本
android/app/build.gradle.kts 或 build.gradle compileSdk、minSdk、应用配置 全版本
android/gradle.properties 全局开关（如 AGP 9 的 newDsl） 全版本
android/local.properties SDK 路径（自动生成，一般不用改） 全版本

新手常踩坑 ：升了 flutter upgrade，以为 Android 构建配置也升了------并没有 ，必须手动检查 android/ 里的版本。

1.3 盖房子类比（快速理解各组件）

工具 通俗理解 Flutter 项目位置
Flutter SDK 总包工程师（Dart + 引擎） 全局 flutter 命令
Flutter Gradle Plugin 把 Flutter 引擎接入 Android 打包 Flutter SDK 自带
AGP Android 专用施工规范 android/settings.gradle.kts
Gradle 施工队调度系统 android/gradle/wrapper/
Kotlin (KGP) 部分插件/原生代码的语言 android/settings.gradle.kts
JDK 施工语言环境 Studio Gradle JDK（随 AGP 变化，见 2.1 表）

升级顺序（Flutter 项目）：

text 复制代码 
flutter upgrade  →  确认 Flutter 版本支持目标 AGP
       ↓
JDK（见 2.1 表）  →  Gradle  →  AGP  →  Kotlin
       ↓
逐个检查 pub.dev 插件的 android/ 兼容性
       ↓
flutter clean && flutter build apk 验证

二、Flutter 版本与 android/ 模板默认值

Flutter 每个稳定版在源码 gradle_utils.dart 与项目模板中定义了新建项目时 android/ 的默认值。老项目不会自动跟上，升级时需手动对照下表。

数据来源：

过往版本速查：Flutter 全部稳定版发布记录 | Flutter 破坏性变更

2.1 Flutter 稳定版 Android 构建链完整对照表（官方）

下表按 Flutter 稳定版小版本 列出，可直接用于升级对照。

JDK 列 依据 AGP 官方最低 JDK 要求 推导（非 Flutter 单独声明）。

配置文件列指新建项目模板的 AGP/Kotlin 声明位置，老项目可能仍是更早格式。

Flutter Dart AGP Gradle Kotlin compileSdk minSdk targetSdk NDK JDK 配置文件 发布日期 备注
3.44.0 3.12.0 9.0.1 9.1.0 2.3.20 36 24 36 28.2.13676358 17 settings.gradle.kts 2026-05-18 AGP 9；内置 Kotlin；模板仍保留 KGP 声明作过渡
3.41.0 3.11.0 8.11.1 8.14 2.2.20 36 24 36 28.2.13676358 17 settings.gradle.kts 2026-02-11 ---
3.38.0 3.10.0* 8.11.1 8.14 2.2.20 36 24 36 28.2.13676358 17 settings.gradle.kts 2025-11-12 *归档标注为 3.10.0 beta 构建
3.35.1 3.9.0 8.9.1 8.12 2.1.0 36 24 36 27.0.12077973 17 settings.gradle.kts 2025-08-14 minSdk 升至 24
3.32.0 3.8.0 8.7.3 8.12 2.1.0 35 21 35 26.1.10909125 17 settings.gradle.kts 2025-05-20 ---
3.29.0 3.7.0 8.7.0 8.10.2 1.8.22 35 21 35 26.1.10909125 17 settings.gradle.kts 2025-02-12 新建模板切 .kts
3.27.0 3.6.0 8.1.0 8.3 1.8.22 35 21 35 26.1.10909125 17 settings.gradle 2024-12-11 AGP 8.x 起点
3.22.0 3.4.0 7.3.0 7.6.3 1.7.10 34 21 34 23.1.7779620 11 settings.gradle 2024-05-13 minSdk 升至 21
3.19.0 3.3.0 7.3.0 7.6.3 1.7.10 34 19 33 23.1.7779620 11 settings.gradle 2024-02-15 ---
3.16.0 3.2.0 7.3.0 7.5 1.7.10 33 19 33 23.1.7779620 11 settings.gradle 2023-11-15 ---
3.13.0 3.1.0 7.3.0 7.5 1.7.10 33 19 33 23.1.7779620 11 settings.gradle 2023-08-16 compileSdk 升至 33
3.10.0 3.0.0 7.3.0 7.5 1.7.10 31 16 31 23.1.7779620 11 settings.gradle 2023-05-10 ---
3.7.0 2.19.0 7.2.0 7.5 1.7.10 31 16 31 21.4.7075529 11 build.gradle 2023-01-24 ---
3.3.0 2.18.0 7.1.2 7.4 1.6.10 31 16 31 21.1.6352462 11 build.gradle 2022-08-30 ---
3.0.0 2.17.0 7.1.2 7.4 1.6.10 31 16 31 21.1.6352462 11 build.gradle 2022-05-11 ---
2.10.0 2.16.0 4.1.0 6.7 1.6.10 31 16 31 --- 8 build.gradle 2022-02-03 老模板根 build.gradle
2.0.0 2.12.0 4.1.0 6.7 1.3.50 30 16 30 --- 8 build.gradle 2021-03-03 Null Safety 首发稳定版

查法 ：在 Flutter 归档页 找到目标 Flutter 版本 → 记下 Ref（Git commit）→ 打开 https://github.com/flutter/flutter/blob/<Ref>/packages/flutter_tools/lib/src/android/gradle_utils.dart 核对模板常量。

2.1 补充：为什么表里没有 AGP 8.12 / 8.13？

AGP 8.13 是存在的 ，Google 在 过往 AGP 发布说明 和 8.13.0 发布说明 中均有记录（2025 年 9 月，8.x 最终大版本之一）。

2.1 表按 Flutter 稳定版列出 ，只收录各 Flutter 版本新建项目模板的默认值。Flutter 官方稳定版从未把 8.12 / 8.13 作为模板默认 AGP：

区间 Flutter 模板 AGP 说明
3.41 / 3.38 8.11.1 8.x 时代 Flutter 模板的最后默认值
3.44 9.0.1 直接跳到 AGP 9，跳过了 8.12、8.13
Google 8.x 最终版 8.13.2 存在，但需手动配置，见下文

Flutter 项目是否需要 AGP 8.13？

场景 建议
跟着 Flutter 官方模板走 不需要。3.41 用 8.11.1，3.44 用 9.0.1，按 2.1 表即可
不想升 AGP 9，但要 Kotlin 2.3 / compileSdk 36.1 可以手动升到 8.13.2 （Kotlin 2.3 最低 AGP 8.13.2）
纯 Android 项目 / 不用 Flutter 工具链校验 按 Google 第三节、第四节表升级即可

手动使用 AGP 8.13 的推荐组合 （Flutter 3.41+，非模板默认）：

组件 版本 来源
AGP 8.13.2 AGP 8.13 发布说明（8.13.2 起支持 Kotlin 2.3）
Gradle 8.13 同上（AGP 8.13 最低 Gradle 8.13）
Kotlin 2.3.21 Kotlin 支持表
JDK 17 AGP 8.0+ 要求
Flutter SDK ≥ 3.41（建议 3.44+） 3.44 工具链校验支持 AGP 至 9.1，含 8.13 兼容映射

Flutter 3.44 的 gradle_utils.dart 内置了 AGP 8.13 → Gradle 8.13 的对应关系，手动配置可以构建 ，但需自行验证 pub.dev 插件兼容性。详见 第七节 7.2「保守留 8.x」 与 第八节路径 B。

同类「Google 有、Flutter 模板未默认」的 AGP 版本（2.1 表同样不会出现）：

AGP Google 状态 Flutter 最近模板对照
8.10.x 官方有 3.29 模板为 8.7.0
8.12.x 官方有 3.35 模板为 8.9.1
8.13.x 8.x 最终版 3.41 模板为 8.11.1，3.44 跳到 9.0.1

2.2 版本演进关键节点（速览）

阶段 Flutter 版本 主要变化
早期 2.0 ~ 2.10 AGP 4.1 + Gradle 6.7；根 android/build.gradle 声明 classpath；JDK 8
AGP 7 时代 3.0 ~ 3.22 AGP 7.1 ~ 7.3；Gradle 7.4 ~ 7.6；Kotlin 1.6 ~ 1.7；JDK 11 （AGP 7.0+ 要求）
AGP 8 时代 3.27 ~ 3.41 AGP 8.1 ~ 8.11；Gradle 8.3 ~ 8.14；Kotlin 1.8 ~ 2.2；JDK 17 （AGP 8.0+ 要求）
AGP 9 时代 3.44+ AGP 9.0.1 + Gradle 9.1；Kotlin 2.3.20；内置 Kotlin ；见 迁移指南

配置文件演进（新建项目模板）：

时期 典型文件
2.x ~ 3.10 android/build.gradle + app/build.gradle
3.16 ~ 3.28 android/settings.gradle（Groovy）
3.29+ android/settings.gradle.kts + app/build.gradle.kts

升级时优先对照 ：目标 Flutter 版本所在行的 AGP + Gradle + Kotlin 三件套，再交叉验证第三节 AGP ↔ Gradle 官方表。

2.3 Flutter 工具链当前支持上限（截至 2026，以 Flutter 3.44.0 为准）

Flutter SDK 内置校验逻辑（gradle_utils.dart，3.44.0 tag）当前大致支持：

组件 Flutter 3.44 工具链上限 说明
AGP 9.1 模板默认仍为 9.0.1
Gradle 9.3.1 模板默认 9.1.0
Kotlin (KGP) 2.3.20 与模板一致

注意 ：此上限随 Flutter SDK 版本变化。例如 Flutter 3.41 的工具链上限为 AGP 9.0 / Gradle 9.1.0 / KGP 2.2.20，不要跨 Flutter 版本套用。
意思 ：你可以手动把 android/ 升到 AGP 9.2，但 Flutter 工具链可能尚未完全校验通过，建议以 Flutter 模板推荐值为准，或关注 Flutter AGP 9 适配 Issue。

2.4 怎么知道自己项目该用什么版本？

方法一（推荐）：用当前 Flutter 版本新建临时项目对比

bash 复制代码 
flutter create temp_check
# 对比 temp_check/android/ 与你项目的 android/ 配置差异

方法二：看 Flutter 版本

bash 复制代码 
flutter --version

然后对照上表 2.1 完整对照表，再与下文第三节 AGP-Gradle 官方表交叉验证。

三、基础层：AGP 与 Gradle 版本对应表

AGP 与 Gradle 是构建链底座 。Flutter 项目的配置在 android/ 里，规则与纯 Android 项目相同。

来源：Google 官方 - 关于 Android Gradle 插件

过往版本速查：

3.1 最新版本速查

用法 ：先定 AGP，查 Gradle，两个一起改。Flutter 完整组合见第七节 7.2。

目标 AGP Gradle Kotlin JDK 最高 API
最新稳定 9.2.0 9.4.1 2.3.21 17 37
次新稳定 9.1.1 9.3.1 2.3.21 17 37
Flutter 3.44+ 模板 9.0.1 9.1.0 2.3.20 17 36.1
8.x 最终版 8.13.2 8.13 2.3.21 17 36.1

3.2 完整对照表（AGP 7.0 ~ 9.2）

AGP 版本 最低 Gradle 推荐 Gradle
9.2 9.4.1 9.4.1
9.1 9.3.1 9.3.1
9.0 9.1.0 9.1.0
8.13 8.13 8.13
8.12 8.13 8.13
8.11 8.13 8.13
8.10 8.11.1 8.11.1
8.9 8.11.1 8.11.1
8.8 8.10.2 8.10.2
8.7 8.9 8.9
8.6 8.7 8.7
8.5 8.7 8.7
8.4 8.6 8.6
8.3 8.4 8.4
8.2 8.2 8.2
8.1 8.0 8.0
8.0 8.0 8.0
7.4 7.5 7.5
7.3 7.4 7.4
7.2 7.3.3 7.3.3
7.1 7.2 7.2
7.0 7.0 7.0

进阶提示 ：Gradle 可以高于最低版本，但建议用发布说明默认版本。同时确认不超过 第二节 2.3 Flutter 工具链上限。

四、各 AGP 大版本完整工具链

过往版本速查：Android Gradle 插件过往发布说明

4.1 AGP 9.2.0（2026 年 4 月）

组件 最低 默认
Gradle 9.4.1 9.4.1
Build Tools 36.0.0 36.0.0
NDK --- 28.2.13676358
JDK 17 17

4.2 AGP 9.1.1（2026 年 4 月）

组件 最低 默认
Gradle 9.3.1 9.3.1
Build Tools 36.0.0 36.0.0
JDK 17 17

4.3 AGP 9.0.1（2026 年 1 月）------ Flutter 3.44+ 模板版本

组件 最低 默认
Gradle 9.1.0 9.1.0
Build Tools 36.0.0 36.0.0
JDK 17 17

对 Flutter 项目的重大影响：

开关 9.0 默认 Flutter 项目影响
android.newDsl true 部分 Flutter 插件的旧 AGP API 可能不兼容
android.builtInKotlin true 模板已迁移内置 Kotlin，老插件可能仍引用 kotlin-android

Flutter 官方适配：迁移到内置 Kotlin（Flutter 版）

4.4 AGP 8.13.0（2025 年 9 月，8.x 最终版）

官方文档：AGP 8.13.0 发布说明 | 过往 AGP 版本索引

注意 ：Flutter 稳定版模板从未默认 8.13（3.41 停在 8.11.1，3.44 跳到 9.0.1），见 2.1 补充。

组件 最低 默认
Gradle 8.13 8.13
Build Tools 35.0.0 35.0.0
JDK 17 17
  • 最高 API：36.1；8.13.2 起支持 Kotlin 2.3

五、Android Studio 与 AGP

用 Android Studio 打开 android/ 目录调试原生问题时需要关注。

来源：about-agp - Studio 兼容性

过往版本速查：Android Studio 发布说明

Studio 代号 版本号 支持 AGP
Quail 1 2026.1.1 7.1 ~ 9.2
Panda 4 2025.3.4 7.1 ~ 9.2
Panda 3 2025.3.3 7.0 ~ 9.1
Otter 2 FD 2025.2.2 4.1 ~ 8.13
Meerkat 2024.3.1 3.2 ~ 8.9

Flutter 日常开发用 VS Code 也行，但升级 android/ 遇到 Gradle Sync 问题，建议用 Android Studio 打开 android/ 目录排查。

六、compileSdk 与 Google Play 要求

Google Play 要求提高 targetSdk 时，Flutter 项目改 android/app/build.gradle.kts。

来源：about-agp - API 级别最低工具版本

过往版本速查：AGP 过往发布说明

API 级别 最低 AGP 最低 Gradle 最低 Studio
37 9.1.1 9.3.1 Panda 3
36.1 8.13.0 8.13 Narwhal 3 FD
36 8.9.1 8.11.1 Meerkat
35 8.6.0 8.7 Koala FD
34 8.1.1 8.0 Hedgehog

Flutter 项目示例 （android/app/build.gradle.kts）：

kotlin 复制代码 
android {
    compileSdk = 36
    defaultConfig {
        targetSdk = 36
    }
}

七、Kotlin、KSP 及 JDK 版本对齐

Kotlin 插件必须和 AGP、Gradle 一起查表。Flutter 3.44+ 新建项目已默认使用 AGP 9 内置 Kotlin。

7.1 Kotlin 版本 → 最低 AGP

来源：Kotlin 版本所需的 AGP 版本

过往版本速查：Kotlin 发布记录 | KGP 历史兼容表

Kotlin 最低 AGP 最低 R8
2.4 9.1.0 9.1.29
2.3 8.13.2 8.13.19
2.2 8.10 8.10.21
2.1 8.6 8.6.17
2.0 8.5 8.5.10
1.9 8.0 8.0.27

9.0.28 之前的 AGP 9.x 不支持 Kotlin 2.3。

7.2 三合一推荐组合表（Flutter 项目直接照抄）

首选 ：直接查 第二节 2.1 完整对照表 中与你 flutter --version 一致的行。

下表为常见升级场景的快捷组合（可超出 Flutter 模板，需自行验证插件兼容性）。

场景 Flutter 版本参考 AGP Gradle Kotlin JDK
跟 Flutter 最新模板 3.44.0（见 2.1 表） 9.0.1 9.1.0 2.3.20 17
稳定 AGP 9.1 3.44+ 9.1.1 9.3.1 2.3.21 17
最新 AGP 9.2 关注 Flutter 适配 9.2.0 9.4.1 2.3.21 17
保守留 8.x（Google 8.x 最终版，非 Flutter 模板） 3.29 ~ 3.41 8.13.2 8.13 2.3.21 17
老项目 3.22 及更早（见 2.1 表） 7.3.0 7.6.3 1.7.10 11

过往版本速查：AGP 过往发布说明 | Gradle 所有版本

Flutter 项目配置示例 （android/settings.gradle.kts）：

kotlin 复制代码 
plugins {
    id("dev.flutter.flutter-plugin-loader") version "1.0.0"
    id("com.android.application") version "9.0.1" apply false
    id("org.jetbrains.kotlin.android") version "2.3.20" apply false
}

7.3 KSP 版本（用了相关 Flutter 插件时）

来源：KSP GitHub Releases

过往版本速查：KSP 全部历史版本

KGP KSP
2.3.21 2.3.21-2.0.2
2.3.20 2.3.20-2.0.x（查 Releases）
2.2.21 2.2.21-2.0.2

格式：KGP版本-KSP编译器版本，必须主版本一致。部分 Flutter 插件（如 json_serializable 的 Android 侧）间接依赖 KSP。

7.4 AGP 9 内置 Kotlin（Flutter 3.44+ 必读）

来源：Flutter - 迁移到内置 Kotlin

过往版本速查：AGP 9.0 发布说明

以前（Flutter 老模板） 现在（Flutter 3.44+ / AGP 9）
settings.gradle.kts 里声明 kotlin-android AGP 9 内置 Kotlin ，理论上可不再手动声明；3.44 模板仍保留 KGP 行作过渡
插件各自管 KGP 版本 需确保插件不冲突
kapt 可用 kapt 与内置 Kotlin 不兼容，插件应迁 KSP

过渡期 （插件尚未适配时，android/gradle.properties）：

properties 复制代码 
android.newDsl=false
android.builtInKotlin=false

AGP 10.0 将移除这些开关。Flutter 团队正在推进插件生态适配 AGP 9。

7.5 JDK 与 Gradle / AGP

来源：Gradle 兼容性矩阵

过往版本速查：Gradle Java 兼容详情

组件 JDK 要求
AGP 4.x JDK 8
AGP 7.x JDK 11
AGP 8.0+ JDK 17
Gradle 9.x 运行需 JVM 17 ~ 25

Flutter 开发者通常在 Android Studio 中设置：Settings → Build Tools → Gradle → Gradle JDK → 17。

7.6 关于 Compose Compiler（补充）

Flutter UI 用 Widget 体系，一般不需要 Jetpack Compose 。仅当你在 android/ 里写了 Compose 原生模块，或混用 Android 原生页面时，才需对齐 Compose Compiler 与 Kotlin 版本（Kotlin 2.0+ 规则：Compiler 版本 = Kotlin 版本）。

过往版本速查：Compose 与 Kotlin 兼容表

八、Flutter 项目升级路径

路径 A：跟着 Flutter 官方走（推荐）

适合：愿意保持与 Flutter 模板一致的项目

步骤 操作
1 flutter upgrade 升到 3.44+
2 对比新建项目的 android/ 配置
3 逐步把老项目 android/ 对齐到模板（AGP 9.0.1 + Gradle 9.1.0 + KGP 2.3.20）
4 逐个检查 pub.dev 插件兼容性
5 flutter clean && flutter build apk

路径 B：保守派 ------ 暂留 8.x（Google 最高 8.x，超出 Flutter 模板）

适合：插件多、暂不想碰 AGP 9 的生产项目

注意：Flutter 3.41 模板为 AGP 8.11.1 ，下表是 Google 8.x 最终版 8.13.2，属于手动超模板升级，需自行验证插件兼容性。

步骤 AGP Gradle Kotlin
1 8.10 8.11.1 2.2.21
2 8.13.2 8.13 2.3.21

每步执行 flutter build apk 验证。

路径 C：激进派 ------ 最新 AGP 9.2

适合：新项目，或插件生态已适配

目标 AGP Gradle Kotlin
最终 9.2.0 9.4.1 2.3.21

先确认 Flutter 工具链支持（第二节 2.3），并关注 Flutter AGP 9 适配进度。

升 AGP 9 前清单：

  • Flutter ≥ 3.44？
  • 所有 pub.dev 插件是否有 AGP 9 兼容版？
  • android/gradle.properties 是否还需要 newDsl=false？
  • flutter build apk 和 flutter run 都测过？

九、手把手：Flutter 项目改 android/ 哪些文件？

9.1 改 AGP + Kotlin（android/settings.gradle.kts）

kotlin 复制代码 
plugins {
    id("dev.flutter.flutter-plugin-loader") version "1.0.0"
    id("com.android.application") version "9.0.1" apply false
    // AGP 9 内置 Kotlin 后，新建模板可能不再声明下面这行
    id("org.jetbrains.kotlin.android") version "2.3.20" apply false
}

9.2 改 Gradle（android/gradle/wrapper/gradle-wrapper.properties）

properties 复制代码 
distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip

或在 android/ 目录下：

bash 复制代码 
cd android
./gradlew wrapper --gradle-version 9.1.0

9.3 改 compileSdk（android/app/build.gradle.kts）

kotlin 复制代码 
android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = flutter.minSdkVersion
        targetSdk = 36
    }
}

9.4 过渡期开关（android/gradle.properties）

properties 复制代码 
android.newDsl=false
android.builtInKotlin=false

9.5 验证构建

bash 复制代码 
flutter clean
flutter pub get
flutter build apk --verbose

--verbose 能看到具体是哪个 Gradle 任务、哪个插件报错。

十、Flutter 项目 AGP 9 避坑

10.1 Flutter 插件是最大变量

每个 pub.dev 插件都有自己的 android/build.gradle，可能锁死旧 AGP/Kotlin。升级后如果报：

text 复制代码 
A problem occurred configuring project ':flutter_plugin_name'

解法 ：查插件 GitHub Issues → 升级插件版本 → 不行就暂时 android.newDsl=false。

10.2 典型报错

报错 原因 解法
Minimum supported Gradle version is x.x 只升了 AGP 没升 Gradle 先改 gradle-wrapper.properties
already on classpath 内置 Kotlin + 手动 kotlin-android 冲突 对齐 Flutter 3.44+ 模板，或设 builtInKotlin=false
flutter run 可以但 flutter build apk 失败 release 构建配置更严格 查 android/app/build.gradle.kts 的 release 配置
某插件 compileSdk 太低 插件未更新 升插件或 fork 修改

十一、升级操作清单（Flutter 版）

text 复制代码 
□ 1. flutter --version，确认 Flutter SDK 版本
□ 2. 查第二节 2.1：按 Flutter 版本查 AGP / Gradle / Kotlin 完整对照表
□ 3. 查第三节：AGP → Gradle 官方对应表
□ 4. 查第七节 7.2：三合一推荐组合
□ 5. 确认 JDK 版本（见 2.1 表：8 / 11 / 17）
□ 6. 先改 android/gradle/wrapper/gradle-wrapper.properties
□ 7. 再改 android/settings.gradle.kts
□ 8. 按需改 android/app/build.gradle.kts（compileSdk）
□ 9. 逐个检查 pub.dev 插件兼容性
□ 10. flutter clean && flutter pub get
□ 11. flutter build apk --verbose
□ 12. flutter run 真机/模拟器验证

黄金法则 ：flutter upgrade ≠ 升级 android/。先升 Flutter，再手动对齐 android/，最后查插件。

十二、常见问题 FAQ

Q1：我只做了 flutter upgrade，为什么构建还是报错？

因为 flutter upgrade 只升 Flutter SDK ，不会改你项目 android/ 里已有的 AGP/Gradle 版本。需要手动对比 第二节 2.1 完整对照表 来升级。

Q2：Flutter 版本和 AGP 版本必须完全一致吗？

不必须完全一致，但应满足：

  1. Google 官方 AGP ↔ Gradle 表（第三节）
  2. Flutter 工具链支持上限（第二节 2.3）
  3. 所有 pub.dev 插件兼容

Q3：能不能把 AGP 升到 9.2，Flutter 还用 3.38？

不建议。老 Flutter 版本的 Gradle Plugin 可能不支持新 AGP。建议 先升 Flutter 到 3.44+，再升 AGP。

Q4：纯 Flutter 项目需要管 Kotlin 版本吗？

需要。即使你不写 Kotlin，Flutter 插件和 Flutter Gradle Plugin 的 Android 侧依赖 Kotlin 工具链。版本不对，插件编译就会失败。

Q5：需要管 KSP / Compose 吗？

  • KSP：仅当插件或你的原生代码用到时
  • Compose：Flutter 项目通常不需要（UI 用 Flutter Widget）

Q6：第三方插件不兼容 AGP 9 怎么办？

  1. 升插件到最新版
  2. android/gradle.properties 临时设 android.newDsl=false
  3. 实在不行，AGP 停在 8.13，等插件更新

Q7：Gradle 版本能不能比表里更高？

可以 ≥ 最低版本，但不要超过 Flutter 工具链上限（第二节 2.3），否则 flutter build 可能警告。

十三、旧版附录（考古用）

AGP 所需 Gradle
4.2.0+ 6.7.1
4.1.0+ 6.5+
4.0.0+ 6.1.1+
3.6.x 5.6.4+
3.3.x 4.10.1+
3.0.0+ 4.1+

十四、官方参考资料

Flutter 相关

文档 链接
Flutter SDK 归档列表 https://docs.flutter.cn/install/archive
Flutter 发布说明 https://docs.flutter.dev/release/release-notes
Flutter 破坏性变更 https://docs.flutter.dev/release/breaking-changes
迁移到内置 Kotlin（Flutter） https://docs.flutter.dev/release/breaking-changes/migrate-to-built-in-kotlin
Flutter AGP 9 适配跟踪 https://github.com/flutter/flutter/issues/181557

Android 构建链

文档 链接
关于 Android Gradle 插件 https://developer.android.google.cn/build/releases/about-agp?hl=zh-cn
当前最新 AGP 发布说明 https://developer.android.google.cn/build/releases/gradle-plugin?hl=zh-cn
Kotlin 版本所需的 AGP https://developer.android.google.cn/build/kotlin-support?hl=zh-cn
Gradle 兼容性矩阵 https://docs.gradle.org/current/userguide/compatibility.html

过往版本速查

组件 链接
Android Gradle 插件 https://developer.android.google.cn/build/releases/past-releases?hl=zh-cn
Gradle https://gradle.org/releases/
Kotlin https://kotlinlang.org/docs/releases.html#release-details
KSP https://github.com/google/ksp/releases
Android Studio https://developer.android.google.cn/studio/releases?hl=zh-cn
AGP 路线图 https://developer.android.google.cn/build/releases/gradle-plugin-roadmap?hl=zh-cn

结语

Flutter 打 Android 包，版本管理其实是两层对齐：

  1. Flutter SDK 层 ：flutter upgrade 决定模板推荐值和支持上限
  2. android/ 层：AGP、Gradle、Kotlin 按本文表格手动对齐
  3. 插件层 ：pub.dev 每个插件的 android/ 也要兼容

建议收藏本文，下次 flutter build apk 报错时，按 第二节 → 第三节 → 第七节 7.2 → 第十一节清单 逐步排查。

热门推荐
012026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？022026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点062026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？07AI科技热点日报 | 2026年6月1日08上线仅72小时被强制下架：Claude Fable 5 的短命09Codex 下载安装指南：Windows 和 macOS 官方版下载10AI一周事件 · 2026-06-03 至 2026-06-09