Flutter 仓库依赖自动滚动（Autorollers）机制全解：Clang、Fuchsia SDK、Skia、Dart 与 Pub 依赖的自动化更新实践

Flutter 框架与引擎的日常开发高度依赖大量第三方上游组件，本指南以 docs/infra/Autorollers.md 为骨架，系统讲解 Flutter 仓库如何通过自动滚动（Autoroll）机器人持续跟进 Clang、Fuchsia SDK、Skia、Dart SDK 以及 framework 侧 pub 依赖的更新。读完本文，你将理解每个 roller 修改的是仓库中的哪个文件、在什么情况下会失败、上游变更导致的失败应如何处理，以及作为 Flutter 开发者如何手动完成依赖升级与 Cherry-pick 滚动。

一、什么是 Autoroller：让依赖更新由机器人代劳

Flutter 仓库的依赖更新遵循一条核心原则：不要手动、零星地提交依赖升级，而是让专门的机器人（bot）持续完成。原因很直观：上游（Clang、Skia、Dart 等）几乎每天都在发布新提交，若依赖长期滞后，等真正需要升级时往往面临海量冲突与难以定位的编译回归；反之由机器人高频小步滚动，每次失败都能被单独、及时地隔离与修复。

这些自动滚动覆盖两类依赖：

• 引擎级依赖（Engine）：Clang 工具链、Fuchsia SDK、Skia、Dart SDK，它们写入仓库根目录的 DEPS 文件；
• 框架级依赖（Framework）：framework 各 package 的 pubspec 依赖，由 flutter-pub-roller-bot 账户在每次 framework 提交的 post-submit 阶段自动滚动。

由此形成 Flutter 源码树一个有趣的结构事实：无论是本仓库还是引擎 checkout，根目录 DEPS 的头部注释都写明——“The dependencies referenced by the Flutter Engine”，并说明该文件被 checkout 根部的 .gclient 引用，修改后需执行 gclient sync 才能生效。换句话说，所有自动滚动最终都会落地成 DEPS 文件（或 pubspec 文件）的一行变更 + 一个提交。

二、核心机制：Roller 在改什么——DEPS 与 CIPD

要理解各类 roller，必须先理解它操作的载体 DEPS。以本仓库根目录 DEPS 为例，其顶部 vars 段集中定义了供底层依赖条目引用的“版本变量”：

vars = {
  'dart_ai_rev': '9c96bfe5f091c9451eff5b59c9bffeb2e806b875',
  'skia_revision': 'b6b00df360e5bc0366e747be84bb530ea866a7e6',
  'clang_version': 'git_revision:80743bd43fd5b38fedc503308e7a652e23d3ec93',
  'dart_revision': '5501d02b583d1717b800ada2ac4967e85ead15d8',
  ...
}

DEPS 文件同时支持两种依赖获取协议（dep_type），这是区分 roller 工作方式的关键：

1. git 依赖：直接从远程 git 仓库 checkout 指定 revision，例如 Skia：

   'engine/src/flutter/third_party/skia':
    Var('skia_git') + '/skia.git' + '@' +  Var('skia_revision'),
   

2. CIPD 依赖：从 Chromium 基础设施的 CIPD（Chrome Infra Packages Deployer）拉取二进制包，例如 Clang 在各平台 buildtools 下的条目：

   'engine/src/flutter/buildtools/linux-x64/clang': {
     'packages': [
       {
         'package': 'fuchsia/third_party/clang/linux-amd64',
         'version': Var('clang_version'),
       }
     ],
     'condition': 'host_os == "linux" or host_os == "mac"',
     'dep_type': 'cipd',
   },
   

   同样的结构在 mac-x64、mac-arm64、linux-arm64、windows-x64 上各有一份，DEPS 中注释指出“它们被拆分是为了让 autoroller 更容易管理”（DEPS）。

Fuchsia SDK 同样以 CIPD 方式进入，例如 DEPS 中：

'engine/src/third_party/fuchsia-sdk/sdk': {
   'packages': [
     {
      'package': 'fuchsia/sdk/core/linux-amd64',
      'version': 'GTZNkoIR_WegRPWgLdFwKu1aAPvj4N72-LUqtVJqA_wC'
     }
   ],
   'condition': 'download_fuchsia_deps and not download_fuchsia_sdk',
   'dep_type': 'cipd',
 },

因此文档给出的通用排查手段是：当 roller 更新了 CIPD 包版本后，若你怀疑某个具体 git revision 引入了问题，可以直接在 CIPD 中反查“从 CIPD 版本映射到 git revision / JIRI snapshot”。Clang 与 Fuchsia SDK 的滚动均遵循这一模式。

值得注意的边界是：CIPD 的 package 命名与底层 git 仓库并不直接对应（例如 Clang 的 CIPD 包路径是 fuchsia/third_party/clang/<platform>，Fuchsia SDK 是 fuchsia/sdk/core/<platform>），所以“版本号”多数是 CIPD 实例 ID 或 git_revision:<hash> 形式，而真正的源码历史仍要回到上游 git 中核对。

三、Clang 自动滚动

Flutter 使用 Clang 作为默认编译工具链，由自动滚动面板上的 clang-flutter roller（Flutter 的 Clang roll）持续跟进新版本。

3.1 它修改什么

Roller 把 fuchsia/third_party/clang/* 各平台 CIPD 包在 DEPS 中 clang_version 变量替换为新版本号，例如把 git_revision:80743b... 推进到更新的 commit。DEPS 头部注释明确说明：Flutter 采用与 Dart/Fuchsia 相同的 GN 与 Clang 工具链，revision 需要与 Dart 拉取的工具链保持同步，若工具链出现问题可联系 fuchsia-toolchain。

3.2 失败场景与应对

Clang roll 失败通常源于两种上游变化：

• 新的编译告警或错误：新 Clang 会启用更严格的检查，此前能编译通过的代码现在报错，典型如引擎 C++ 代码触发新 warning；
• 测试依赖了已变化的行为：若某个测试（或其依赖代码）隐式依赖了未定义行为（undefined behavior），在新 Clang 修订版下行为改变会导致测试失败。

文档给出的处理原则是：尽快解决此类问题，让 roller 继续运转，避免问题堆积（a pile up of issues）。此外 DEPS 还补充了一个重要约束：当 Clang 是手动滚动（即自动滚动被禁用）时，必须运行 post-submit 任务（如 Clang Tidy 相关检查），以确认 Clang Tidy 的升级不会让整个 CI 树变红。

四、Fuchsia SDK 自动滚动

Fuchsia SDK 的自动滚动（Linux 平台的 fuchsia-linux-sdk-flutter roller）用于保持引擎对 Fuchsia 目标的构建能力。

4.1 它修改什么

与 Clang 一致，roller 直接更新 DEPS 中 Fuchsia SDK 对应 CIPD 包（fuchsia/sdk/core/<platform>）的实例版本。由于 Fuchsia 侧的版本管理并不总是等价于单个 git commit，文档特别提醒：在 CIPD 中可将版本映射为 JIRI snapshot 或 git revision 再做进一步排查——这是它与 Clang roll（映射纯 git revision）的差异点。

4.2 失败场景与应对

Fuchsia SDK roll 失败的最常见原因是SDK 自身包含破坏性变更（breaking change），例如某个编译接口、构建脚本或平台服务被移除或改动。处理方式同样是“尽早解决、避免堆积”。从 DEPS 条件表达式看，Fuchsia 相关依赖默认只在 Linux x64 宿主下载（download_fuchsia_deps、download_fuchsia_sdk 两个开关控制），本地复现时需确保 host 环境与 CI 一致（DEPS）。

五、Skia 自动滚动

Skia 是 Flutter 渲染引擎依赖的核心图形库，其滚动由专门的 Skia Roll 服务维护。

5.1 它修改什么

Skia roller 更新的是 DEPS 中的 skia_revision 一行（DEPS vars 区与 engine/src/flutter/third_party/skia 的 git 依赖条目均引用该变量，见 DEPS）。相比 CIPD 类滚动，Skia 是纯粹的 git revision 推进，可在上游 Skia 仓库直接核对 commit 内容。

5.2 失败时的协作流程

文档给出了一套明确的协作协议：

1. 出现构建失败或其他错误时，先在 Flutter-Skia 聊天频道中联系相关人员；
2. 若长时间无人响应，可用具备权限（@google.com 账户）登录并暂停该 roller（或请有权限者代为暂停）；
3. 暂停时必须填写有意义的理由（descriptive reason）；
4. 尽快提交 bug，以便在问题解决后重新启用 roller。

这套“先沟通、再暂停、务必登记理由并提 bug 恢复”的流程，是处理自动滚动故障的标准动作，同样适用于其他 roller。

六、Dart SDK 自动滚动

Dart SDK 由 dart-sdk-flutter 自动滚动器推进。它的目标同样是根目录 DEPS 中的 dart_revision 变量（引擎使用的 Dart 源码版本）。

文档同时给出该流程的负责人边界：若自动滚动流程本身或 autoroller 仪表盘出现异常，应联系 bkonyi@ 或 Dart VM 团队的成员，而不是自行猜测处理。

DEPS 中对 Dart 滚动补充了一条关键操作提醒：当更新 Dart revision 时，所有作为 Dart 依赖的条目也必须同步更新到与该 Dart SDK revision 匹配的版本（以 Dart SDK 自己的 DEPS 为准）；仓库提供工具脚本 //tools/dart/create_updated_flutter_deps.py 用于生成已存在依赖的更新 revision 列表，并且在更新前后各执行一次 gclient sync 以校验变更。这与 docs/infra/Rolling-Dart.md（Dart 滚动专篇）和 docs/infra/Bumping-the-Dart-SDK-version.md（Dart SDK 版本升级流程）互为补充。

七、Flutter Pub Roller：framework 侧 pub 依赖的自动更新

与前述四个引擎级 roller 不同，Flutter Pub Roller 面向 framework 的 pub 依赖，是本文档唯一给出具体实现源码的自动滚动器。

7.1 运行方式与触发时机

文档说明：机器人账户 flutter-pub-roller-bot 在 每一次 framework 提交的 post-submit 阶段执行 dev/packages_autoroller 目录下的脚本，以保持 framework 的 pub 依赖始终最新。该目录 README 进一步指出，脚本由 LUCI bot（CI 构建器 “Linux packages_autoroller”）执行以生成依赖更新 PR，本地复现命令为：

./dev/packages_autoroller/run

运行脚本内部会先对 dev/packages_autoroller 执行 flutter pub get，再以 dart --enable-asserts dev/packages_autoroller/bin/packages_autoroller.dart 启动主程序。

7.2 一次完整 roll 的内部流程

从核心实现 dev/packages_autoroller/lib/src/packages_autoroller.dart 的 roll() 方法可以看出，一次 pub 自动滚动包含以下确定步骤：

1. 登录 GitHub CLI：通过 gh auth login --with-token 完成认证（token 为空会直接抛异常），并在日志输出中做 token 脱敏（_redactToken）防止泄密；
2. 防重复检查：调用 gh pr list 检查是否已有标题为 “Roll pub packages” 的 open PR，若存在则直接跳过本次 roll，避免同时存在多个滚动 PR；
3. 创建新分支：分支名固定为 packages-autoroller-branch-<N>，每次递增序号、不复用旧分支；
4. 更新依赖：在新分支上执行 flutter update-packages --force-upgrade；
5. 判断是否有实际变更：若执行后 git checkout 依然干净，说明“包已处于最新”，直接返回、不建 PR；
6. 生成 Gradle lockfile：通过 flutter pub build cli 预编译 generate_gradle_lockfiles 工具，再以 --no-gradle-generation --no-exclusion 重新生成 Android Gradle lockfile；若出现非 .lockfile 结尾的改动（NonLockfileChanges）会抛错中止；
7. 提交并推送：先提交 “roll packages”，再视情况提交 “Re-generate Gradle lockfiles”，随后把分支推送到 org 下的 mirror 仓库；
8. 创建 PR：调用 gh pr create，标题为 “Roll pub packages”，body 注明由 flutter update-packages --force-upgrade 生成，并打上 tool 与 autosubmit 两个 label。

其对应单元测试位于 dev/packages_autoroller/test/packages_autoroller_test.dart，可用于本地验证 roller 逻辑。

7.3 手动执行依赖更新的三个姿势

Pub roller 底层调用的正是 flutter_tools 的 update-packages 命令，完整的命令行用法记录在 docs/infra/Updating-dependencies-in-Flutter.md：

• 更新全部依赖（等价于 roller 的动作）：

  flutter update-packages --force-upgrade
  

• 临时钉住某个依赖：当某个依赖必须被排除在 --force-upgrade 之外时，先在 update_packages_pins.dart 的 kManuallyPinnedDependencies 常量中把它钉住，并附上指向解钉 issue 的注释，再重新运行 flutter update-packages --force-upgrade。这是一个“临时止血 + 留下解钉 TODO”的规范做法。

• 为 Cherry-pick 更新单个依赖：当需要针对 release candidate 分支单独升级某个包时，使用：

  flutter update-packages --cherry-pick=[pub package name]:[pub package version],[pub package2 name]:[pub package2 version]
  

  例如一次性升级 test 相关三个包：

  flutter update-packages --cherry-pick=test_api:0.7.6,test_core:0.6.10,test:1.26.1
  

  该场景完整流程见 docs/releases/Flutter-Cherrypick-Process.md。

八、Roll 失败后的通用处理清单

综合上述五个 roller，可将失败处理归纳为可复用的操作清单：

阶段	动作	依据 / 来源
定位	确认 roll 更新的是哪个变量（clang_version / fuchsia_sdk / skia_revision / dart_revision / pub 依赖），并在 CIPD 或上游 git 反查对应 revision	DEPS vars 区
评估	区分“上游破坏性变更”与“新编译器告警 / 依赖未定义行为改变导致测试失败”两类成因	Autorollers 文档 Clang、Fuchsia 章节
处置	尽早修复，避免问题堆积；需要暂停 roller 时须注明描述性理由并提 bug 以便尽快重新启用	Skia 章节协作协议
人工兜底	用 flutter update-packages --force-upgrade 手动推进；用 kManuallyPinnedDependencies 钉住依赖；用 --cherry-pick 精确升级	Updating-dependencies-in-Flutter.md
上报	Dart roll 相关问题联系 bkonyi@ / Dart VM 团队；Skia roll 联系 Flutter-Skia 频道	Autorollers 文档 Dart、Skia 章节

九、延伸阅读与监控入口

• docs/infra/Dashboards.md：CI/roll 状态总览与各类仪表盘说明，用于跟踪 roller 是否在持续绿灯；
• docs/infra/Updating-dependencies-in-Flutter.md：framework pub 依赖的手动更新全命令参考；
• docs/infra/Rolling-Dart.md：Dart SDK roll 的专题文档；
• docs/infra/Bumping-the-Dart-SDK-version.md：Dart SDK 大版本升级的完整流程；
• docs/releases/Flutter-Cherrypick-Process.md：单依赖/单修复向 release 分支 Cherry-pick 的标准流程；
• dev/packages_autoroller/README.md 与 dev/packages_autoroller/lib/src/packages_autoroller.dart：Pub Roller 的实现细节与本地运行入口。

综上，Flutter 的依赖更新体系可以概括为一句操作心智模型：引擎侧的 Clang、Fuchsia SDK、Skia、Dart 都只是机器人对根目录 DEPS 中一个版本变量的例行推进，framework 侧则是 pub roller 在每次提交后对 pubspec 依赖的 --force-upgrade 循环。理解它们各自修改的载体、失败模式与处理协议，就能在 CI 变红的第一时间给出正确反应，而不是与机器人的节奏互相拉扯。