如何用 dart_roll_helper.py 把新的 Dart SDK 版本 roll 进 Flutter 引擎
【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter
Flutter 仓库通过DEPS文件维护与其他仓库的版本对应关系，Flutter 引擎使用哪个版本的 Dart SDK 就由它决定。Rolling-Dart.md 说明 Dart SDK 目前已由 autoroller 定期自动 roll 进 Flutter 仓库，同一篇文档也完整记录了如何用dart_roll_helper.py手动完成一次 roll。当你明确知道要引入的目标 Dart 修订、需要自己执行并跟踪一次完整 roll 时，走这条路径：脚本负责更新DEPS、同步依赖、生成 GN、构建引擎、跑测试并生成 commit，脚本无错误结束后，再按文档走完 PR 审查与 build bot 验证，整个 roll 才算完成。
执行前的准备
- 按 CONTRIBUTING.md 中 contributing guide 的指引设置好 Engine 与 Flutter 开发环境，并且能够按 Compiling-the-engine.md 构建引擎。这两点来自文档手动 roll 流程的第 1、2 步，是执行 roll 的前置条件。
- 确定以下三个路径，可以用环境变量设置，也可以在命令行上为每个仓库提供
--REPO-home参数。文档明确说明这些路径是工具运行的必要条件：$FLUTTER_HOME：flutter目录的绝对路径；$ENGINE_HOME：engine/src目录的绝对路径；$DART_SDK_HOME：Dart SDK 项目根目录的绝对路径。
- 确保仓库处于干净状态。脚本会执行
gclient sync，文档特别提示它可能删除文件，所以未提交或本地修改过的内容应先处理。 - 选定目标 Dart 修订，即命令中的
$TARGET_SDK_HASH。文档手动流程中的选择标准是：通常选用最新修订，并确认该修订在 Dart buildbot 与 Internal Dart Flutter buildbot 上的测试全部通过（all green）。
运行脚本完成 roll 的自动步骤
文档给出的命令：
python $ENGINE_HOME/tools/dart/dart_roll_helper.py --create-commit $TARGET_SDK_HASH其中$TARGET_SDK_HASH替换为你选定的 Dart 修订 hash。--create-commit用于生成包含相关 Dart SDK commit 日志的 commit——文档把“生成 commit”列为脚本的可选能力之一，命令示例中保留了该参数。如果上文三个环境变量没有设置，需要为每个仓库补充--REPO-home参数。
一次运行中，脚本自动完成的工作包括（均出自文档）：
- 更新
DEPS中的 Dart 修订与 Dart 依赖； - 通过
gclient sync同步依赖； - 为相关引擎配置生成 GN 文件并构建这些配置；
- 在
example/flutter_gallery与packages/flutter中运行测试； - 以 release 和 debug 模式启动 flutter_gallery；
- 运行
license.sh并更新flutter/ci/licenses_golden中的 license 文件； - 生成包含相关 Dart SDK commit 日志的 commit（可选）。
这些动作都会改动工作区（DEPS、生成文件、构建产物、license 文件），因此第 3 条“仓库保持干净状态”不是可选项。
脚本结束后的验证与合入
文档给出的成功条件是脚本无错误地完成。此时按同一文档手动流程的第 10 步起继续：
推送 roll 分支：
git push origin <your_roll_branch_name><your_roll_branch_name>替换为你实际使用的分支名。为 PR 完成 code review，确认 flutter engine build bot 是 green，然后合入 PR。
等 build bot 构建你的变更并保持 green。
bot 变 green 后，Autorollers 会把引擎 roll 进 flutter/flutter 仓库。此时需要监控 flutter build bots 与 benchmarks dashboard：
- 出现失败：在 flutter/engine 中 revert 这次 Dart roll，调试问题并修复，或向 Dart 提 P0 issue；
- 发现性能回归：为所有回归提 P0 issue，并且 revert Dart roll；这些问题修复之前，下一次 roll 会被阻塞。
文档第 14 步还要求：roll 完成后在团队维护的 roll 记录表中登记 roll 进引擎的 Dart 修订 hash，并通知列表中的下一位接手 roll 的人。该链接指向 Google 内部系统，属于团队内部流程。
边界与限制
- Dart 现在默认由 autoroller 定期自动 roll，本文的手动路径面向明确选择目标修订、由人执行并跟踪的场景，两者不是并行竞争的两条主流程。
- 脚本只覆盖 roll 的自动部分，到生成 commit 为止；PR 审查、build bot 验证、失败后的 revert 与后续监控都需要人工完成。
- 手动流程中提到的
create_updated_flutter_deps.py、libraries.yaml更新等步骤属于手工 roll 的对应操作，dart_roll_helper.py路径下文档未要求单独执行，这里不作展开。
【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
