Flutter 仓库 Android 工具链版本选型指南Android API 与 Gradle/AGP/Kotlin 版本兼容规则详解【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter本文基于 Flutter 官方贡献者文档 Android-API-And-Related-Versions.md系统讲解在 flutter/flutter 代码库中为测试、示例和集成工程选择 Android 工具链版本compileSdk、targetSdk、AGP、Gradle、Kotlin、Java 编译选项的规则与依据并结合 gradle_utils.dart 与 DependencyVersionChecker.kt 的源码实现说明这些规则如何被 Flutter 工具链在构建期强制校验。读完本文你将掌握为 Flutter 仓库中的任何 Android 工程做版本选型时选什么、为什么、怎么改以及这些版本约束在构建流程中的底层校验机制。核心原则版本兼容优先差异必须注释文档开宗明义地指出最重要的事情是任何测试、工程或应用都使用相互兼容的版本组合The most important thing is for any test, project, or app to have compatible versions。在此基础上文档确立了三条硬性规则版本需要偏离基线时必须附带注释说明偏离原因和当前正在评估什么例如Testing backwards compatibility of feature XYZ。所有选定的版本必须能通过 DependencyVersionChecker 定义的最低版本检查。这个 Kotlin 对象运行在 Flutter Gradle Plugin 中在构建时逐一校验项目的 Gradle、Java、AGP、KGPKotlin Gradle Plugin和 minSdk 版本低于 error 阈值直接抛出DependencyValidationException使构建失败低于 warn 阈值则打印警告并提示可用--android-skip-build-dependency-validation标志绕过检查。如果所选版本是 gradle_utils.dart 尚不认识的版本必须同步更新 gradle_utils.dart。该文件维护了完整的版本兼容性矩阵详见后文版本校验的底层实现一节工具链的flutter analyze --suggestions等建议功能依赖它做跨版本兼容性判断。compileSdk编译用 SDK 级别的规则文档对compileSdk提出四条约束必须大于或等于targetSdk应使用新版属性名compileSdk而不是旧版compileSdkVersion若无法使用flutter.compileSdkVersion即由 Flutter Gradle Plugin 注入的版本变量则应使用 CIPD 上可用的最大稳定值若刻意选择低于最大值的 API 级别必须附注释说明原因。文档给出的正反示例// OK android { compileSdk flutter.compileSdkVersion }// OK if flutter.compileSdkVersion is not available like in an add to app example. android { compileSdk 35 }// NOT OK android { compileSdk 28 }最后一个示例之所以 NOT OK是因为 28 远低于基线值且没有注释解释为何刻意降级——这在 review 中会被直接要求修正。从源码看flutter.compileSdkVersion这一变量的默认值定义在 FlutterExtension.kt 中当前为36同一常量也在 gradle_utils.dart 中镜像为compileSdkVersionInt 36供工具链侧使用。因此当前仓库基线下硬编码 compileSdk 时可选的最高稳定值就是 36文档示例中的35属于低于最大值但可接受的写法前提是它出现在 add-to-app 等无法使用 flutter 扩展变量的场景中。targetSdk目标 SDK 可以滞后于 compileSdktargetSdk的规则必须大于或等于minSdk应使用targetSdk而非旧版targetSdkVersion文档特别说明targetSdk的提升需要大量人工验证工作——这是 AGP 团队的设计决策因此targetSdk允许滞后于compileSdk若targetSdk刻意选择与其他版本不同的值必须附注释。// OK defaultConfig { targetSdk flutter.targetSdkVersion }// OK if flutter.compileSdkVersion is not available like in an add to app example. defaultConfig { targetSdk 35 }// NOT OK defaultConfig { targetSdk 28 }对应源码中FlutterExtension.kt 注释明确指出 targetSdkVersion should always be the latest available stable version当前默认值为36gradle_utils.dart 中targetSdkVersion 36与其保持一致。注意两个文件中的注释都要求改动这些值时必须同时更新另一处交叉引用机制这也是文档第 3 条更新 gradle_utils.dart规则的具体落点。AGPAndroid Gradle Plugin 版本规则AGP 即构建脚本中的com.android.application、com.android.library插件或旧式 classpath 依赖com.android.tools.build:gradle。文档规则是AGP 版本应为Flutter 模板中设定的版本或更新的版本若刻意选择不同版本必须附注释说明原因。// OK dependencies { classpath com.android.tools.build:gradle:8.8.1 }// OK dependencies { // Testing backwards compatibility of feature XYZ classpath com.android.tools.build:gradle:7.5.2 }文档示例中的 8.8.1 / 7.5.2 是撰写时点的取值。以当前仓库为准模板基线已由 gradle_utils.dart 定义为templateAndroidGradlePluginVersion 9.1.0flutter create生成工程时通过 project.dart 将该值注入模板占位符{{agpVersion}}可参见 plugin 模板 中的classpath(com.android.tools.build:gradle:{{agpVersion}})。Gradle跨小版本最不易出问题的组件文档认为 Gradle 版本是跨小版本更新时最不容易破坏构建的组件因此规则相对宽松新代码中Gradle 版本应为 Flutter 模板设定版本或更新老代码中任何满足其他版本约束的 Gradle 版本都可以接受因为实际客户使用着大量多样的 Gradle 版本刻意选用不同版本时需注释。distributionUrlhttps\://services.gradle.org/distributions/gradle-8.12.1-bin.zip仓库中的落地方式模板文件 gradle-wrapper.properties.tmpl 中distributionUrl使用{{gradleVersion}}占位符运行时由templateDefaultGradleVersion 9.3.1gradle_utils.dart填充。值得注意的细节是当项目缺少 wrapper 文件时GradleUtils.injectGradleWrapperIfNeeded 会依据检测到的 AGP 版本反推合适的 Gradle 版本来自动生成gradle-wrapper.properties——这正是版本兼容优先原则在工具链中的体现。KotlinKGP版本冲突的主要来源文档指出更改 Kotlin 版本时最可能出现的问题是与另一个依赖的冲突而不是被测试代码本身。规则Kotlin 版本应为 Flutter 模板设定版本或更新刻意选不同版本必须附注释。// Ok ext.kotlin_version 1.7.10 ... classpath org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version这个ext.kotlin_version写法是旧式 Groovy DSL 风格文档示例保留它以覆盖存量工程。当前仓库的新模板已改用settings.gradle(.kts)的 plugins 块声明 KGP见 app 模板 settings.gradle.kts.tmplid(org.jetbrains.kotlin.android) version {{kotlinVersion}} apply false其中{{kotlinVersion}}当前由templateKotlinGradlePluginVersion 2.4.0注入gradle_utils.dart。compileOptions 与 kotlinOptionsJava 版本必须一致且用枚举写法这一节的规则最为机械、也最容易被 CI 检查sourceCompatibility必须使用JavaVersion.*枚举形式targetCompatibility必须使用JavaVersion.*枚举形式kotlinOptions的jvmTarget应与compileOptions使用的 Java 版本一致不一致必须注释jvmTarget应使用JavaVersion.SOMEVERSION.toString()否则需注释。// Correct configuration compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } kotlinOptions { jvmTarget JavaVersion.VERSION_17.toString() }// Not ok, kotlinOptions uses a string. compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } kotlinOptions { jvmTarget 17 }// Not ok, different versions of java compileOptions { sourceCompatibility JavaVersion.VERSION_11 targetCompatibility JavaVersion.VERSION_11 } kotlinOptions { jvmTarget JavaVersion.VERSION_17.toString() }第一个示例不合规的原因是把jvmTarget写成裸字符串17绕过了JavaVersion枚举约束第二个示例不合规的原因是 Kotlin 目标字节码17与 Java 编译目标11不一致会产生混用字节码版本的隐患。版本校验的底层实现常量、阈值与兼容矩阵文档中必须通过 DependencyVersionChecker 检查和必须更新 gradle_utils.dart两条规则在仓库中有清晰的源码落点。模板基线版本gradle_utils.dartgradle_utils.dart 集中定义了模板默认版本文件头注释明确写着these are the versions used in the project templates……Please see the README before changing any of these values并逐项列出改值时需要联动更新的位置DependencyVersionChecker 的 warn 版本、Kotlin 测试常量等。当前基线为常量当前值含义templateDefaultGradleVersion9.3.1模板默认 Gradle 版本templateAndroidGradlePluginVersion9.1.0模板默认 AGP 版本templateKotlinGradlePluginVersion2.4.0模板默认 KGP 版本compileSdkVersionInt36默认 compileSdkminSdkVersionInt24默认 minSdktargetSdkVersion36默认 targetSdkndkVersion28.2.13676358默认 NDK 版本warnJavaMinVersionAndroid/errorJavaMinVersionAndroid17Java 最低版本要求这份常量与 FlutterExtension.kt 中 Gradle 侧暴露给build.gradle.kts的flutter.compileSdkVersion、flutter.minSdkVersion、flutter.targetSdkVersion一一对应——工具链Dart 侧与构建脚本Kotlin 侧通过这组镜像常量保持同步。支持区间阈值DependencyVersionChecker.ktDependencyVersionChecker.kt 为每类依赖定义了 warn即将不支持与 error立即报错两级阈值依赖warn 版本error 版本Gradle9.1.08.14.0Java1717AGP9.0.18.11.1KGP2.3.202.2.20minSdk2423源码注释特别说明了一个贡献流程约束在更新某个 error 版本之前必须先在一个完整发布周期内更新对应的 warn 版本以提前告知用户。这解释了为什么表中有两档阈值而不是单一最低值。检查入口 checkDependencyVersions 还会为每个构建变体注册*MinSdkCheck任务并让assemble*任务依赖它保证 minSdk 检查覆盖所有 flavor。跨版本兼容矩阵gradle_utils.dart 的 validate* 函数gradle_utils.dart 后半部分实现了四组版本对的兼容性判断这正是文档要求新出现的未知版本必须回填此文件的原因validateGradleAndKGPKGP 2.4.0 要求 Gradle 8.59.5 区间KGP 1.7.x 要求 Gradle 6.7.17.0.2 等validateAgpAndKgpKGP 2.4.0 对应 AGP 8.2.29.2 区间KGP 1.6.20 对应 AGP 3.4.37.0.2 区间等validateGradleAndAgp覆盖 AGP 3.3.0 到 9.1.x 全谱系的最低 Gradle 要求如 AGP 9.1.x 要求 Gradle ≥ 9.3.1AGP 8.8.x 要求 Gradle ≥ 8.10.2validateJavaAndGradle依据 Gradle 官方兼容性矩阵判断 Java 与 Gradle 的组合。这些函数的注释表明其用途是flutter analyze --suggestions等工具能力给定项目中的任一版本组合工具链可以回答这套版本互相兼容吗。若用户项目出现了矩阵之外的新版本函数会打印 Unknown ... compatibility 并返回不兼容此时就触发文档中update gradle_utils.dart的义务。对照官方模板一份完全合规的 build.gradle.kts最好的校验方式是看仓库自己的 app 模板 build.gradle.kts.tmpl它逐条满足文档全部规则android { namespace {{androidIdentifier}} compileSdk flutter.compileSdkVersion // 规则优先使用 flutter 变量 ndkVersion flutter.ndkVersion compileOptions { sourceCompatibility JavaVersion.VERSION_17 // 规则JavaVersion.* 枚举 targetCompatibility JavaVersion.VERSION_17 } defaultConfig { minSdk flutter.minSdkVersion // 24 targetSdk flutter.targetSdkVersion // 36 minSdk versionCode flutter.versionCode versionName flutter.versionName } // ... } kotlin { compilerOptions { jvmTarget org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 // 与 compileOptions 一致 } }可以观察到两个演进点一是新版 Kotlin DSL 将kotlinOptions { jvmTarget }替换为kotlin { compilerOptions { jvmTarget } }取值改用JvmTarget.JVM_17枚举本质上仍是文档必须与 compileOptions 一致、必须用枚举形式规则的最新表达二是文档中flutter.compileSdkVersion这类属性确实由 FlutterExtension.kt 定义的FlutterExtension扩展对象提供默认值与 Dart 侧常量严格对齐。实践要点小结在 flutter/flutter 仓库中新增或修改任何 Android 构建配置时先查 gradle_utils.dart 的模板基线当前Gradle 9.3.1 / AGP 9.1.0 / KGP 2.4.0 / compileSdk 36 / targetSdk 36 / minSdk 24优先使用flutter.*变量而非硬编码。必须偏离基线时如评估向后兼容按文档要求写明为什么不同的注释并确认版本仍高于 DependencyVersionChecker.kt 的 error 阈值当前Gradle ≥ 8.14.0、AGP ≥ 8.11.1、KGP ≥ 2.2.20、Java ≥ 17、minSdk ≥ 23否则 CI 构建会直接失败。引入工具链尚不认识的版本时同步维护 gradle_utils.dart 中的常量与四组validate*兼容矩阵并在文件头注释所列的联动位置DependencyVersionChecker 的 warn 版本、Kotlin 测试常量中更新对应值。Java 编译目标统一使用JavaVersion.VERSION_17及对应 KotlinjvmTarget避免字符串写法与 Java/Kotlin 目标版本不一致这两类典型违规。【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考