Flutter 适配新 Android API 级别New Android API Level的完整维护指南【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter每年 Android 都会在秋季与春季发布新的 API 级别而 Flutter 开发者期望在新版本可用后第一时间基于它构建应用。本文以 New-Android-version.md 为核心骨架系统梳理 Flutter 仓库从新版 Android 发布到Flutter 全链路适配所需的全部工作项从调研破坏性变更、升级 Robolectric、把 Android SDK 上传到 CIPD到引擎与模板的 SDK 版本提升、AVD 与真机测试环境的更新等。读完本文你将掌握一套可逐年复用的 Android API 升级 SOP并能在本仓库中定位每一个对应的实现文件与配置。一、适配新 Android API 级别的目标与整体策略1.1 为什么每年都要做这件事每当 Android 发布新的 API 版本Flutter 都必须保证 Android 上的 Flutter 应用能在该新版本上继续成功构建。达成目标的两条主线分别是处理新 API 引入的行为变更behavioral changes与破坏性变更breaking changes——这部分工作内容逐年不同取决于该版本 Android 的具体改动更新基础设施以针对新 API 做测试——更新 Flutter on Android 的 CI这部分流程每年基本一致可以沉淀成标准操作。文档同时给出一个重要建议按顺序执行下面的步骤如果某一步被阻塞例如上游尚未发布支持新 API 的依赖就跳到下一步继续不必死等。此外该文档本身也需要与时俱进维护者应持续更新其中记录的流程、Issue 与 PR。1.2 总体工作流一览适配工作大体包含以下工作区后文逐一展开创建升级到新 API 的 umbrella伞形跟踪Issue调研新版 Android 功能与破坏性变更提升仓库内 samples 的 compile/target SDK更新 Robolectric 版本更新本地工具链、模拟器与真机到新 API将新 Android SDK 及相关依赖上传至 CIPD更新 SDK 与依赖版本支持CI、packages、引擎、模板、既有 App在 Firebase Test Lab 与内部真机实验室中添加新 API 设备更新 Flutter 管理的模拟器 AVD 镜像必要时升级 CI 中的 Java LTS 版本更新文档与integration_test示例。二、前期准备Umbrella Issue 与功能调研2.1 创建伞形跟踪 Issue为升级到新 API创建一个 umbrella Issue 用于串联所有子任务与 PR。原文档给出过从 API 35 升级到 API 36 的跟踪示例flutter/flutter issue #163071。跟踪 Issue 中应覆盖上文的每一步便于社区与团队按链接定位进展。2.2 调研新版 Android 特性与潜在影响新版 Android 的特性可能给 Flutter 带来破坏性或行为上的变更工作量跨度很大。Flutter Android 团队应逐项调研新 API 特性判断哪些是no-op无需处理、哪些需要实际投入开发。在实践中团队通常对新版本的破坏性变更已有所预判会提前排期因此这一步的产出是要不要做、做什么的决策清单。2.3 提升 samples 的 compile/target SDK仓库中的 samples尤其是 add-to-app 这类示例代表最早一批采用新 Android API 的用户画像因此要优先把它们的 compile SDK 与 target SDK 提升到新版本。这一阶段以 flutter/samples 仓库的改动为主起到探路作用。三、更新 Robolectric 测试依赖Robolectric 是一个允许我们在本地开发机上、无需真实 Android 设备即可针对 Android API 编写单元测试的依赖。升级流程为查看 Robolectric 官方 release notes确认是否有支持新 Android API 的版本。如果尚未发布则此步被阻塞直到新版本发布才能继续在flutter/flutter含 engine与flutter/packages中查找所有 Robolectric 用法并逐一更新到新版本。在本仓库中Robolectric 驱动的宿主工程测试主要位于 dev/integration_tests/android_engine_test、dev/integration_tests/android_semantics_testing 等基于 Gradle 的 Android 测试工程中升级时可参照这些工程内对robolectric依赖的引用做全局检索例如搜索robolectric以确认改动范围。四、更新本地工具链与测试设备更新本地开发与测试设施是验证新 API 的前提升级 Android Studio到支持新 API 的版本新增至少一台运行新 Android API 的模拟器用于测试将至少一台物理设备升级到新 Android API用于测试。具体版本要求以官方发布的 New Android API release notes 为准。五、将新 Android SDK 上传到 CIPD关键步骤Flutter 通过 CIPD 保存一份稳定、可归档的 Android SDK 副本engine 与 LUCI recipes 都依赖这些 CIPD 包。上传脚本位于本仓库 create_cipd_packages.sh。5.1 权限与安全须知上传 CIPD 包需要flutter-cipd-writers角色授予后需运行cipd auth-login刷新可用角色上传到 CIPD 前务必核对文本文件中的 SDK 配置上传操作难以撤销务必谨慎。若确实需要移除已上传的 CIPD tag需走对应的内部 playbook 流程不要手工逐个上传新版 Android API 到 CIPD应统一使用仓库脚本。5.2 packages.txt声明要打包的 SDK 组件需要打包的 SDK 组件声明在 packages.txt每行格式为package_name:subdirectory_to_uploadpackage_name使用sdkmanager的包标识如platforms;android-36、build-tools;36.1.0、ndk;28.2.13676358通常更新到最新可用版本可用sdkmanager --list --include_obsolete查询sdkmanager位于 Android SDK 的commandline-tools中subdirectory_to_upload表示该包在 SDK 目录中需要上传的子目录如platforms、build-tools、cmdline-tools冒号后的子目录也可用额外:分隔声明多个同一组件需要上传多个版本时用逗号分隔例如本仓库当前配置保留了对 android-34 至 android-37 多个平台的归档platforms;android-37.0,platforms;android-36,platforms;android-35,platforms;android-34:platforms cmdline-tools;latest:cmdline-tools build-tools;37.0.0,build-tools;36.1.0,build-tools;36.0.0,build-tools;35.0.0,build-tools;34.0.0,build-tools;33.0.1:build-tools platform-tools:platform-tools cmake;3.22.1:cmake ndk;28.2.13676358:ndk5.3 执行上传脚本在脚本目录下执行cd tools/android_sdk ./create_cipd_packages.sh your-tag-version your-local-sdk-path脚本行为要点可从 create_cipd_packages.sh 源码确认参数一your-tag-version只能包含小写字母与数字例如37v2它既是 CIPD 的-tag version:也会被用作-ref引用名参数二为本地 SDK 目录省略时默认取环境变量ANDROID_SDK_ROOT运行前要求cipd在 PATH 中需 depot_toolsSDK 内需已安装cmdline-tools默认优先使用cmdline-tools/latest/bin/sdkmanager找不到时会自动搜索其它版本支持./create_cipd_packages.sh list直接列出所有可用包等价于执行sdkmanager --list --include_obsolete脚本会为linux / macosx / windows三平台分别创建临时干净 SDK 目录逐个按 packages.txt 安装组件把声明的子目录与许可文件复制到上传目录再以cipd create上传为flutter/android/sdk/all/platform-archmacOS 额外上传 arm64 版本以支持 M1 机器linux/windows 只上传 amd64完成后清理临时目录。上传完成后为 SDK 配置改动提交一个 PR 留存paper trail——虽然上传本身不依赖该 PR 合并但能让后续维护者无需反查 CIPD 历史即可看到 SDK 配置的演进。说明脚本已在内部取代手工上传。若万不得已需手工上传单个包可用cipd create -in your-android-dir/Android/sdk/some_package -name flutter/android/sdk/some_package -tag version:new-version-tag典型your-android-dir位于~/Library/Android新 tag 将用于在DEPS中引用。5.4 在 DEPS 中切换到新版本 tagengine 顶层 DEPS 中即是通过 CIPD 版本 tag 拉取 Android SDK 与 Gradle 的。仓库当前示例engine/src/flutter/third_party/gradle: { packages: [ { # Version here means the CIPD tag. version: version:9.3.1, package: flutter/gradle } ], ... }, engine/src/flutter/third_party/android_tools: { packages: [ { package: flutter/android/sdk/all/${{platform}}, version: version:37v2 } ], ... }升级 SDK 时把flutter/android/sdk/all/${{platform}}的version改为新上传的 tag例如version:30r2这种命名风格必要时同步上调flutter/gradle对应的 Gradle 版本 tag。六、更新 SDK 与依赖版本支持落地到 CI 与产物新版本 Android 通常会附带新的依赖版本下限。升级顺序有讲究先改内部测试用 App 与 ci.yaml不直接影响用户→ 再改 Flutter 模板直接影响新建应用。6.1 更新 ci.yaml 中的 android_sdk在flutter/flutter与flutter/packages的ci.yaml中把android_sdk版本提升到新 SDK如果必须同时测试新版 Java也要一并更新 ci.yaml。仓库中关于引擎/框架的 CI 配置可参见根目录的ci.yaml及 dev/README.md 相关说明实际改动时以最小化、只涉及版本号为准。6.2 更新 Flutter Android packages 默认值让 packages 仓库的示例工程以新 API 构建更新create_all_packages工具使其以新 API 作为 compile SDK对应 flutter/packages 仓库中script/tool/lib/src/create_all_packages_app_command.dart内 compileSdk 的设置逻辑。6.3 更新 Flutter Android 引擎默认值含文件级清单当新 API 出现后需按下表修改引擎内文件使引擎针对新 API 编译并以其为 target注意仅完成编译目标并不保证新 API 下一切行为正常文件仓库相对路径修改内容当前仓库参考行DEPSflutter/android/sdk/all/${{platform}}的version改为新上传的 CIPD tag当前为version:37v2DEPS必要时把flutter/gradle版本 tag 提升到更新的 Gradle当前为version:9.3.1gen_javadoc.pyclasspath中对android-XX的引用提升到最新版本当前引用android-36android_embedding_bundle/build.gradlecompileSdk XX提升到最新版本当前compileSdk 36shell/platform/android/test_runner/build.gradlecompileSdk XX提升到最新版本当前compileSdk 36shell/platform/android/AndroidManifest.xmlandroid:targetSdkVersionXX提升到最新版本当前targetSdkVersion36native_activity.gniandroid_buildtools中build-tools/XX与android_jar中android-XX提升到最新当前引用build-tools/36.1.0与platforms/android-36/android.jar由于该清单可能过时实际改动时应全局搜索仓库内所有build.gradle中对旧 SDK 版本的引用一并提升到最新版本。6.4 更新仓库内所有既有 Flutter on Android App查看新 API release notes 获取依赖版本下限更新相应 App 的构建依赖新 API 与新依赖版本覆盖flutter/flutter与flutter/packages下的示例与集成测试工程。本仓库中此类工程集中在 dev/integration_tests 下例如 flavors、release_smoke_test 等可对照其build.gradle或build.gradle.kts里的compileSdk/targetSdk进行验证。6.5 更新 Flutter Android 模板模板直接决定用户flutter create新建工程的默认配置影响面最大务必最后执行查看新 API release notes 确定依赖版本下限提交一个 PR 把模板切换到新 API 与新依赖下限此改动不要动模板的targetSdk可能还需要额外的 infra 变更上一步合入且post-submit 检查连续 100 个 commit 不 flaky 之后再开一个新 PR 更新targetSdk。模板更新后即使尚未合并任何内容新建的 Flutter App 就应带上新版本号。合并前必须做冒烟验证命令如下flutter create new-app-name flutter analyze --suggestions # 检查依赖版本兼容性 flutter build apk # 确保应用能成功构建七、接入新真机与 AVD 测试环境7.1 Firebase Test Lab 中的真机/模拟器Firebase Test Lab 的设备支持由 Firebase 团队维护。查看是否已有新 API 物理设备可用gcloud firebase test android models list框架frameworkCI 仅针对物理设备做专项测试若设备尚未上线则需等待或与 Firebase 团队协调。7.2 更新 Flutter 管理的 AVD模拟器镜像Flutter 管理的 engine 模拟器需要支持新 API 的新 AVD 镜像并且 framework、engine、packages 三处应使用同一个 AVD。更新步骤在 Chromium 托管的 AVD CIPDchromium/tools/android/avd/linux-amd64/中找到最新上传的 AVD确认其包含目标 API 对应的generic_android_API#.textpb记录其 instance identifier更新模拟器配置例如在.ci.yamlframework 内中把依赖指向新 AVDlinux_android_emu: properties: contexts: - [ android_virtual_device ] dependencies: - [ ... {dependency: android_virtual_device, version: android_API#_google_apis_x64.textpb}, {dependency: avd_cipd_version, version: build_id:Instance ID}, ]Flutter 使用 Chromium 提供的 AVD。若新 AVD 在 post-submit 测试中失败需与 Chromium 协作定位通常他们会发布带修复的 revision。为了提前验证dogfood可以新建一个测试平台配置并把失败用例先加入bringup。7.3 实验室物理设备分批升级Flutter 维护着一批用于测试上架 App 的 Android 物理设备升级到新 API 需要向 lab manager 提 ticket部分设备可立即升级到新 API或支持新 API 的系统部分需要等待设备厂商发布支持版本届时再跟踪 release notes 并提 ticket不要一次性提交升级所有设备的 ticket必须保证每个测试池仍有足够设备承载测试应分批进行对已到生命周期终点、永远无法支持新 API 的设备应选择规格相当的替代机型。八、Java LTS 版本与文档、integration_test 收尾8.1 升级 CI 中的 Java 版本仅针对 Java LTS 发布每几年 Java 会发布新的 LTS 版本并逐步成为行业标准往往也随新版 Android SDK 被用户采用。此时应把 CI 升级到新 Java 以提前暴露兼容性问题参照 Uploading-New-Java-Version-to-CIPD.md 中的指引把新 Java 版本包上传到 CIPD更新 CI 中对当前 Java 版本的所有引用到新版本。8.2 更新支持平台文档适配完成后需要同步更新官网 supported platforms 文档页面docs.flutter.dev/reference/supported-platforms明确新 API 已进入 Flutter 的测试范围。8.3 测试integration_test包integration_test是随 Flutter 工具发布、用于在 App 上运行集成测试的包。要确保它在最新发布的 stable Flutter 工具上存在一个以新 API 级别为 target 的示例工程本仓库中integration_test的示例代码位于 packages/integration_test/example。九、相关文档与进一步阅读Uploading-New-Java-Version-to-CIPD.md把新 Java 版本上传到 CIPD 的分步指引Update-Android-MinSdkVersion.md提升 Flutter Android 最低 SDKminSdk版本的配套流程Uploading-New-Gradle-Version-to-CIPD.mdGradle 新版本上传到 CIPD 的配套指引Emulators for Flutter Android Testing面向模拟器的 Android 变更测试方法与此文档配套的公开版说明引擎侧 SDK 打包脚本与配置create_cipd_packages.sh、packages.txt。十、总结一份可逐年复用的检查清单创建新 API 升级 umbrella Issue调研新特性判定 no-op 与需处理项samples尤其 add-to-app提升 compile/target SDK更新 Robolectric确认上游已发布支持版本升级 Android Studio、模拟器与真机通过create_cipd_packages.sh上传新 SDK 并提交 packages.txt 变更 PR更新 DEPS 中 SDK/Gradle tag、引擎内各 build.gradle 与 Manifest 的 compile/target SDK更新 ci.yaml、packages 默认值与全部既有测试 App分两步更新 Flutter 模板先版本下限稳定后改 targetSdk并用flutter analyze --suggestions与flutter build apk冒烟验证Firebase Test Lab 真机就绪并更新 AVD 至新 API三端统一实验室真机分批升级保留各池测试余量Java LTS 发布时同步升级 CI 并更新 CIPD更新 supported-platforms 文档与 integration_test 示例。按此清单推进即可在每年 Android 新版本发布后让 Flutter 的框架、引擎、packages 与模板快速、安全地完成新 API 级别的适配与回归验证。【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Flutter 适配新 Android API 级别New Android API Level的完整维护指南【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter每年 Android 都会在秋季与春季发布新的 API 级别而 Flutter 开发者期望在新版本可用后第一时间基于它构建应用。本文以 New-Android-version.md 为核心骨架系统梳理 Flutter 仓库从新版 Android 发布到Flutter 全链路适配所需的全部工作项从调研破坏性变更、升级 Robolectric、把 Android SDK 上传到 CIPD到引擎与模板的 SDK 版本提升、AVD 与真机测试环境的更新等。读完本文你将掌握一套可逐年复用的 Android API 升级 SOP并能在本仓库中定位每一个对应的实现文件与配置。一、适配新 Android API 级别的目标与整体策略1.1 为什么每年都要做这件事每当 Android 发布新的 API 版本Flutter 都必须保证 Android 上的 Flutter 应用能在该新版本上继续成功构建。达成目标的两条主线分别是处理新 API 引入的行为变更behavioral changes与破坏性变更breaking changes——这部分工作内容逐年不同取决于该版本 Android 的具体改动更新基础设施以针对新 API 做测试——更新 Flutter on Android 的 CI这部分流程每年基本一致可以沉淀成标准操作。文档同时给出一个重要建议按顺序执行下面的步骤如果某一步被阻塞例如上游尚未发布支持新 API 的依赖就跳到下一步继续不必死等。此外该文档本身也需要与时俱进维护者应持续更新其中记录的流程、Issue 与 PR。1.2 总体工作流一览适配工作大体包含以下工作区后文逐一展开创建升级到新 API 的 umbrella伞形跟踪Issue调研新版 Android 功能与破坏性变更提升仓库内 samples 的 compile/target SDK更新 Robolectric 版本更新本地工具链、模拟器与真机到新 API将新 Android SDK 及相关依赖上传至 CIPD更新 SDK 与依赖版本支持CI、packages、引擎、模板、既有 App在 Firebase Test Lab 与内部真机实验室中添加新 API 设备更新 Flutter 管理的模拟器 AVD 镜像必要时升级 CI 中的 Java LTS 版本更新文档与integration_test示例。二、前期准备Umbrella Issue 与功能调研2.1 创建伞形跟踪 Issue为升级到新 API创建一个 umbrella Issue 用于串联所有子任务与 PR。原文档给出过从 API 35 升级到 API 36 的跟踪示例flutter/flutter issue #163071。跟踪 Issue 中应覆盖上文的每一步便于社区与团队按链接定位进展。2.2 调研新版 Android 特性与潜在影响新版 Android 的特性可能给 Flutter 带来破坏性或行为上的变更工作量跨度很大。Flutter Android 团队应逐项调研新 API 特性判断哪些是no-op无需处理、哪些需要实际投入开发。在实践中团队通常对新版本的破坏性变更已有所预判会提前排期因此这一步的产出是要不要做、做什么的决策清单。2.3 提升 samples 的 compile/target SDK仓库中的 samples尤其是 add-to-app 这类示例代表最早一批采用新 Android API 的用户画像因此要优先把它们的 compile SDK 与 target SDK 提升到新版本。这一阶段以 flutter/samples 仓库的改动为主起到探路作用。三、更新 Robolectric 测试依赖Robolectric 是一个允许我们在本地开发机上、无需真实 Android 设备即可针对 Android API 编写单元测试的依赖。升级流程为查看 Robolectric 官方 release notes确认是否有支持新 Android API 的版本。如果尚未发布则此步被阻塞直到新版本发布才能继续在flutter/flutter含 engine与flutter/packages中查找所有 Robolectric 用法并逐一更新到新版本。在本仓库中Robolectric 驱动的宿主工程测试主要位于 dev/integration_tests/android_engine_test、dev/integration_tests/android_semantics_testing 等基于 Gradle 的 Android 测试工程中升级时可参照这些工程内对robolectric依赖的引用做全局检索例如搜索robolectric以确认改动范围。四、更新本地工具链与测试设备更新本地开发与测试设施是验证新 API 的前提升级 Android Studio到支持新 API 的版本新增至少一台运行新 Android API 的模拟器用于测试将至少一台物理设备升级到新 Android API用于测试。具体版本要求以官方发布的 New Android API release notes 为准。五、将新 Android SDK 上传到 CIPD关键步骤Flutter 通过 CIPD 保存一份稳定、可归档的 Android SDK 副本engine 与 LUCI recipes 都依赖这些 CIPD 包。上传脚本位于本仓库 create_cipd_packages.sh。5.1 权限与安全须知上传 CIPD 包需要flutter-cipd-writers角色授予后需运行cipd auth-login刷新可用角色上传到 CIPD 前务必核对文本文件中的 SDK 配置上传操作难以撤销务必谨慎。若确实需要移除已上传的 CIPD tag需走对应的内部 playbook 流程不要手工逐个上传新版 Android API 到 CIPD应统一使用仓库脚本。5.2 packages.txt声明要打包的 SDK 组件需要打包的 SDK 组件声明在 packages.txt每行格式为package_name:subdirectory_to_uploadpackage_name使用sdkmanager的包标识如platforms;android-36、build-tools;36.1.0、ndk;28.2.13676358通常更新到最新可用版本可用sdkmanager --list --include_obsolete查询sdkmanager位于 Android SDK 的commandline-tools中subdirectory_to_upload表示该包在 SDK 目录中需要上传的子目录如platforms、build-tools、cmdline-tools冒号后的子目录也可用额外:分隔声明多个同一组件需要上传多个版本时用逗号分隔例如本仓库当前配置保留了对 android-34 至 android-37 多个平台的归档platforms;android-37.0,platforms;android-36,platforms;android-35,platforms;android-34:platforms cmdline-tools;latest:cmdline-tools build-tools;37.0.0,build-tools;36.1.0,build-tools;36.0.0,build-tools;35.0.0,build-tools;34.0.0,build-tools;33.0.1:build-tools platform-tools:platform-tools cmake;3.22.1:cmake ndk;28.2.13676358:ndk5.3 执行上传脚本在脚本目录下执行cd tools/android_sdk ./create_cipd_packages.sh your-tag-version your-local-sdk-path脚本行为要点可从 create_cipd_packages.sh 源码确认参数一your-tag-version只能包含小写字母与数字例如37v2它既是 CIPD 的-tag version:也会被用作-ref引用名参数二为本地 SDK 目录省略时默认取环境变量ANDROID_SDK_ROOT运行前要求cipd在 PATH 中需 depot_toolsSDK 内需已安装cmdline-tools默认优先使用cmdline-tools/latest/bin/sdkmanager找不到时会自动搜索其它版本支持./create_cipd_packages.sh list直接列出所有可用包等价于执行sdkmanager --list --include_obsolete脚本会为linux / macosx / windows三平台分别创建临时干净 SDK 目录逐个按 packages.txt 安装组件把声明的子目录与许可文件复制到上传目录再以cipd create上传为flutter/android/sdk/all/platform-archmacOS 额外上传 arm64 版本以支持 M1 机器linux/windows 只上传 amd64完成后清理临时目录。上传完成后为 SDK 配置改动提交一个 PR 留存paper trail——虽然上传本身不依赖该 PR 合并但能让后续维护者无需反查 CIPD 历史即可看到 SDK 配置的演进。说明脚本已在内部取代手工上传。若万不得已需手工上传单个包可用cipd create -in your-android-dir/Android/sdk/some_package -name flutter/android/sdk/some_package -tag version:new-version-tag典型your-android-dir位于~/Library/Android新 tag 将用于在DEPS中引用。5.4 在 DEPS 中切换到新版本 tagengine 顶层 DEPS 中即是通过 CIPD 版本 tag 拉取 Android SDK 与 Gradle 的。仓库当前示例engine/src/flutter/third_party/gradle: { packages: [ { # Version here means the CIPD tag. version: version:9.3.1, package: flutter/gradle } ], ... }, engine/src/flutter/third_party/android_tools: { packages: [ { package: flutter/android/sdk/all/${{platform}}, version: version:37v2 } ], ... }升级 SDK 时把flutter/android/sdk/all/${{platform}}的version改为新上传的 tag例如version:30r2这种命名风格必要时同步上调flutter/gradle对应的 Gradle 版本 tag。六、更新 SDK 与依赖版本支持落地到 CI 与产物新版本 Android 通常会附带新的依赖版本下限。升级顺序有讲究先改内部测试用 App 与 ci.yaml不直接影响用户→ 再改 Flutter 模板直接影响新建应用。6.1 更新 ci.yaml 中的 android_sdk在flutter/flutter与flutter/packages的ci.yaml中把android_sdk版本提升到新 SDK如果必须同时测试新版 Java也要一并更新 ci.yaml。仓库中关于引擎/框架的 CI 配置可参见根目录的ci.yaml及 dev/README.md 相关说明实际改动时以最小化、只涉及版本号为准。6.2 更新 Flutter Android packages 默认值让 packages 仓库的示例工程以新 API 构建更新create_all_packages工具使其以新 API 作为 compile SDK对应 flutter/packages 仓库中script/tool/lib/src/create_all_packages_app_command.dart内 compileSdk 的设置逻辑。6.3 更新 Flutter Android 引擎默认值含文件级清单当新 API 出现后需按下表修改引擎内文件使引擎针对新 API 编译并以其为 target注意仅完成编译目标并不保证新 API 下一切行为正常文件仓库相对路径修改内容当前仓库参考行DEPSflutter/android/sdk/all/${{platform}}的version改为新上传的 CIPD tag当前为version:37v2DEPS必要时把flutter/gradle版本 tag 提升到更新的 Gradle当前为version:9.3.1gen_javadoc.pyclasspath中对android-XX的引用提升到最新版本当前引用android-36android_embedding_bundle/build.gradlecompileSdk XX提升到最新版本当前compileSdk 36shell/platform/android/test_runner/build.gradlecompileSdk XX提升到最新版本当前compileSdk 36shell/platform/android/AndroidManifest.xmlandroid:targetSdkVersionXX提升到最新版本当前targetSdkVersion36native_activity.gniandroid_buildtools中build-tools/XX与android_jar中android-XX提升到最新当前引用build-tools/36.1.0与platforms/android-36/android.jar由于该清单可能过时实际改动时应全局搜索仓库内所有build.gradle中对旧 SDK 版本的引用一并提升到最新版本。6.4 更新仓库内所有既有 Flutter on Android App查看新 API release notes 获取依赖版本下限更新相应 App 的构建依赖新 API 与新依赖版本覆盖flutter/flutter与flutter/packages下的示例与集成测试工程。本仓库中此类工程集中在 dev/integration_tests 下例如 flavors、release_smoke_test 等可对照其build.gradle或build.gradle.kts里的compileSdk/targetSdk进行验证。6.5 更新 Flutter Android 模板模板直接决定用户flutter create新建工程的默认配置影响面最大务必最后执行查看新 API release notes 确定依赖版本下限提交一个 PR 把模板切换到新 API 与新依赖下限此改动不要动模板的targetSdk可能还需要额外的 infra 变更上一步合入且post-submit 检查连续 100 个 commit 不 flaky 之后再开一个新 PR 更新targetSdk。模板更新后即使尚未合并任何内容新建的 Flutter App 就应带上新版本号。合并前必须做冒烟验证命令如下flutter create new-app-name flutter analyze --suggestions # 检查依赖版本兼容性 flutter build apk # 确保应用能成功构建七、接入新真机与 AVD 测试环境7.1 Firebase Test Lab 中的真机/模拟器Firebase Test Lab 的设备支持由 Firebase 团队维护。查看是否已有新 API 物理设备可用gcloud firebase test android models list框架frameworkCI 仅针对物理设备做专项测试若设备尚未上线则需等待或与 Firebase 团队协调。7.2 更新 Flutter 管理的 AVD模拟器镜像Flutter 管理的 engine 模拟器需要支持新 API 的新 AVD 镜像并且 framework、engine、packages 三处应使用同一个 AVD。更新步骤在 Chromium 托管的 AVD CIPDchromium/tools/android/avd/linux-amd64/中找到最新上传的 AVD确认其包含目标 API 对应的generic_android_API#.textpb记录其 instance identifier更新模拟器配置例如在.ci.yamlframework 内中把依赖指向新 AVDlinux_android_emu: properties: contexts: - [ android_virtual_device ] dependencies: - [ ... {dependency: android_virtual_device, version: android_API#_google_apis_x64.textpb}, {dependency: avd_cipd_version, version: build_id:Instance ID}, ]Flutter 使用 Chromium 提供的 AVD。若新 AVD 在 post-submit 测试中失败需与 Chromium 协作定位通常他们会发布带修复的 revision。为了提前验证dogfood可以新建一个测试平台配置并把失败用例先加入bringup。7.3 实验室物理设备分批升级Flutter 维护着一批用于测试上架 App 的 Android 物理设备升级到新 API 需要向 lab manager 提 ticket部分设备可立即升级到新 API或支持新 API 的系统部分需要等待设备厂商发布支持版本届时再跟踪 release notes 并提 ticket不要一次性提交升级所有设备的 ticket必须保证每个测试池仍有足够设备承载测试应分批进行对已到生命周期终点、永远无法支持新 API 的设备应选择规格相当的替代机型。八、Java LTS 版本与文档、integration_test 收尾8.1 升级 CI 中的 Java 版本仅针对 Java LTS 发布每几年 Java 会发布新的 LTS 版本并逐步成为行业标准往往也随新版 Android SDK 被用户采用。此时应把 CI 升级到新 Java 以提前暴露兼容性问题参照 Uploading-New-Java-Version-to-CIPD.md 中的指引把新 Java 版本包上传到 CIPD更新 CI 中对当前 Java 版本的所有引用到新版本。8.2 更新支持平台文档适配完成后需要同步更新官网 supported platforms 文档页面docs.flutter.dev/reference/supported-platforms明确新 API 已进入 Flutter 的测试范围。8.3 测试integration_test包integration_test是随 Flutter 工具发布、用于在 App 上运行集成测试的包。要确保它在最新发布的 stable Flutter 工具上存在一个以新 API 级别为 target 的示例工程本仓库中integration_test的示例代码位于 packages/integration_test/example。九、相关文档与进一步阅读Uploading-New-Java-Version-to-CIPD.md把新 Java 版本上传到 CIPD 的分步指引Update-Android-MinSdkVersion.md提升 Flutter Android 最低 SDKminSdk版本的配套流程Uploading-New-Gradle-Version-to-CIPD.mdGradle 新版本上传到 CIPD 的配套指引Emulators for Flutter Android Testing面向模拟器的 Android 变更测试方法与此文档配套的公开版说明引擎侧 SDK 打包脚本与配置create_cipd_packages.sh、packages.txt。十、总结一份可逐年复用的检查清单创建新 API 升级 umbrella Issue调研新特性判定 no-op 与需处理项samples尤其 add-to-app提升 compile/target SDK更新 Robolectric确认上游已发布支持版本升级 Android Studio、模拟器与真机通过create_cipd_packages.sh上传新 SDK 并提交 packages.txt 变更 PR更新 DEPS 中 SDK/Gradle tag、引擎内各 build.gradle 与 Manifest 的 compile/target SDK更新 ci.yaml、packages 默认值与全部既有测试 App分两步更新 Flutter 模板先版本下限稳定后改 targetSdk并用flutter analyze --suggestions与flutter build apk冒烟验证Firebase Test Lab 真机就绪并更新 AVD 至新 API三端统一实验室真机分批升级保留各池测试余量Java LTS 发布时同步升级 CI 并更新 CIPD更新 supported-platforms 文档与 integration_test 示例。按此清单推进即可在每年 Android 新版本发布后让 Flutter 的框架、引擎、packages 与模板快速、安全地完成新 API 级别的适配与回归验证。【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
