Flutter Beta 1 发布复盘：从一次 beta 版本发布事故中沉淀的渠道切换、升级验证与 bad-build 流程教训

导读

本文以 Postmortem-Beta-1-Release.md 为主体，复盘 Flutter 在 2018 年 2 月 27 日发布首个 beta（Beta 1）时经历的完整发布过程。读者将了解到：Flutter 的 channel/upgrade 机制在当时有哪些缺陷、为何"内部测试全绿而外部用户升级失败"、bad build（坏构建）为什么需要被主动标记，以及 Flutter 团队事后沉淀出的预防、缓解、流程与修复行动清单。文中同步对照当前仓库中的 channel.dart、upgrade.dart 与渠道版本定义源码，说明当年的教训如何在今天的工具实现中得到体现。

这是一篇"发布后复盘"（postmortem）型文档，关注的是纯技术发布流程层面哪些环节本可以更顺畅——不涉及产品决策或对外公关，仓库中 docs/postmortems/ 目录下收录了多篇此类复盘，Beta 1 发布复盘 是其中结构最完整的一篇（含 Summary、Timeline、Lessons Learned、Action items）。

背景与复盘范围

2018 年 2 月 27 日，Flutter 正式对外宣布首个 beta 版本。复盘文档在开篇即界定了自己的讨论边界：

• 复盘角度：strictly from a technical release process point of view（只从技术发布流程角度），评估"哪些环节本可以做得更顺畅"。
• 复盘载体：时间线（Timeline）+ 经验教训（Lessons Learned）+ 行动项（Action items）三段式。
• 涉及角色：发布执行人（@tvolkert）、分支权限管理者（@Hixie）、尝鲜升级的内部用户（@mit-mit、@timsneath）、以及被拉来协同排查的引擎/渠道相关工程师（@jason-simmons、@cbracken、@mravn-google）。

复盘的直接触发点是：Beta 1 虽按计划在目标日期发布，但发布当天及随后两天暴露出了一系列渠道切换、升级链路、文档同步与 CI 集成方面的真实缺陷，其中多类问题都直接作用于 flutter channel / flutter upgrade 这两个开发者日常高频命令。

事件时间线：从预发布测试到发布后两天的完整经过

原文以精确到分钟的时间线（时区为 PST）记录了整个发布周期，以下按阶段整理。

2018/02/20 – 02/25：候选版本测试期

发布执行人 @tvolkert 开始测试 v0.1.4，为 02/27 的 beta 发布做准备。这个"提前一周做发布候选验证"的动作本身没有问题，问题出在后续暴露的验证盲区上（详见后文"gallery 无法构建未被发现"一节）。

2018/02/26：权限问题与首批升级事故

时间	事件
11:40	@tvolkert 尝试将 v0.1.4 推送到 beta，但因 beta 分支在 GitHub 上受保护（protected branch）而没有足够权限，推送失败。
12:02	@Hixie 将 @tvolkert 加入 beta 分支 ACL，使其能够推送 beta 发布。
12:07	@tvolkert 成功将 v0.1.4 推送到 beta 分支。
12:20	@mit-mit 尝试升级到新 beta 时遇到问题（对应 issue #15096），当时确切原因未知。
12:39	结合 @timsneath 与 @mit-mit 的相似报告，@tvolkert 意识到切换 channel 时并未从 GitHub 拉取更新后的 refs，为此提交 issue #14893。
14:40	@timsneath 在升级中遇到更多麻烦，@tvolkert 开始基于报告远程诊断。
16:53	在与 @timsneath 邮件往返数轮后，@tvolkert 拉上 @jason-simmons 与 @cbracken 一同排查，核心问题是：这是仅影响个别人的孤立环境问题，还是会在用户涌入时波及大多数人的普遍问题？
17:30	@jason-simmons 发现：在 #14507（v0.0.24）之前的旧版本里，channel 命令会创建本地（非跟踪，non-tracking）分支；若 @timsneath 被该 bug 命中，就能解释其现象。团队初步判定这是孤立问题。
20:00	@tvolkert 成功重构出 @timsneath 的环境配置，确认了上述推断。团队在渠道文档中补充了对应的工作区说明，供可能遇到同样问题的用户查阅。

2018/02/27：发布当天

时间	事件
01:48	@mit-mit 发现 gallery 示例无法针对 beta 构建运行，提交 issue #14912。
02:18	@mravn-google 定位到 gallery 构建失败的根因，发现该问题其实已在新版本 v0.1.5（对应 PR #14714）中修复。
06:00	Beta 版本面向公众宣布。
09:30	团队决定将 v0.1.5 推送到 beta 以吸收 gallery 构建修复，@tvolkert 随即开始测试 v0.1.5。

2018/02/28：补丁发布与文档站问题

时间	事件
10:00	@tvolkert 将 v0.1.5 推送到 beta。
10:20	@tvolkert 在 flutter-dev 邮件列表宣布更新后的 beta。
16:00	@tvolkert 发现 docs.flutter.io 并未随 beta 发布更新，提交 issue #15002。

从时间线可以看出两个显著模式：一是发布执行人缺少受保护分支的推送权限，白白消耗时间；二是大量缺陷（渠道 refs 未拉取、gallery 构建失败、文档未同步）都是靠人工尝鲜升级后才暴露，说明当时的验证与 CI 体系存在系统性盲区。

"what worked / what didn't work"：六类技术缺陷的根因分析

做得好的三件事

复盘对发布整体给出了客观评价：

1. Beta 1 按时成功发布，达成了最初设定的目标日期。
2. 绝大多数用户能顺利安装/从 dev 渠道升级到 beta，收到的故障报告很少（仅 #15074、#14959 等少量）。
3. 响应速度合格：gallery 构建失败报告出现后，团队只用了约一天半就完成新 dev build 的验证并推送新 beta。

关键缺陷 1：内部测试（Bazel）不覆盖外部构建路径，导致 gallery 事故未被拦截

Flutter 团队在 Google 内部的一切构建都基于 Bazel，因此内部 Google 测试有意不去执行面向外部用户的构建代码路径（如 Gradle 构建）。后果是：

• gallery 在 beta 分支上无法构建（#14912），但团队在 beta 推送之前对此毫无感知，直到 @mit-mit 手动尝鲜才发现；
• 该缺陷其实已在更新的 dev build（PR #14714）中修复，但由于没有将受影响的构建区间标记为 bad，故障一直处于"没人知道已经坏过"的状态；
• 当时外部测试在 Travis 上允许失败（allow failures）——这是刻意为之，因为彼时对这些测试还没有信心。PR #14714 除修复问题外，也把这些测试在 Travis 上正式启用。

这一条教训直接催生了后文 action items 中的"Travis 必须测试 gallery 可构建性"和"bad builds 标记流程"两项。

关键缺陷 2：channel 命令切换前不拉取远端 refs，旧分支指针悬空

原文记录的 channel 命令缺陷是：在 checkout 分支之前，并没有从 GitHub fetch 更新后的 refs。后果很具体——如果用户曾切到 beta 分支，后来又切回 dev 作为主渠道，那么其本地 beta 的 Git head 会一直指向去年 12 月的某个提交；当用户再想升级回 beta 时，自然升不到最新版。

这段复盘在今天的源码中可以找到直接印证。当前仓库的 channel.dart 中，_checkout 逻辑的第一条命令就是：

// Get latest refs from upstream.
RunResult runResult = await git.run(<String>['fetch'], workingDirectory: Cache.flutterRoot);

随后才通过 git show-ref --verify refs/heads/<branch> 判断本地分支是否存在：存在则直接 git checkout，不存在则以 git checkout --track -b <branch> origin/<branch> 创建带跟踪关系的分支（channel.dart）。也就是说，当年复盘中"先 fetch 再 checkout""必须创建 tracking 分支"这两条教训，如今已是该命令的默认实现路径。

关键缺陷 3：历史 bug 创建的"本地非跟踪分支"让用户卡在 no upstream

截至 2018 年 2 月 7 日（PR #14507）之前，channel 的切换逻辑存在 bug：会把分支创建为本地（非跟踪）分支。这类分支上的用户一旦执行 flutter upgrade，会收到 "no upstream repository configured"（未配置上游仓库）的错误。

受害者画像在复盘中被清晰描绘：

• 只影响 2017 年 12 月曾切到过 beta 分支的用户（该 beta 当时是静默推送的）；
• 波及人数可能极少（或许基本是 Flutter 团队成员），但 @timsneath 恰好是其中之一；
• 因为无法确定这是孤立问题还是会大面积爆发，给发布冲刺阶段增加了不确定性——团队一度拿不准是否该叫停对外发布公告。

升级命令对这类错误的防御至今仍保留在源码中。upgrade.dart 的 fetchLatestVersion 会捕获两条 git 关键错误并给出对应处理建议（upgrade.dart）：

• fatal: HEAD does not point to a branch —— 提示当前不在发布分支上，建议 flutter channel 切换官方渠道或重新安装；
• fatal: no upstream configured for branch —— 正是当年的 "no upstream" 场景，提示当前渠道未跟踪任何远程仓库，建议重装 Flutter。

关键缺陷 4：升级验证无法"停在目标版本"，模拟不了真实用户升级路径

发布流程文档要求执行发布的人验证目标 build：

可以从更早的 dev build 成功升级到该版本（通过 flutter upgrade）； 可以从该版本成功升级到后续 dev build（通过 flutter upgrade）。

但当时的工具存在一个结构性限制：没有任何办法让升级精确停在目标 build 上——flutter upgrade 总是升到对应分支的 tip-of-tree。这意味着执行发布的人体验到的升级路径，与用户实际走的升级路径并不一致。更隐蔽的是，流程里写的是"从更早的 dev build 升级"，而 beta 老用户实际上是从上一个 beta 版本升级，这两者并不等价——正是这个表述上的细微差别，让团队没能预判到老 beta 用户会被 #15096 命中。

当时模拟用户升级路径的替代手段是执行 git reset --hard <old-version>，但执行发布的人持有的是全新 clone，而真实用户（尤其只留在 beta 渠道、只在有新 beta 时才升级的用户）的 Git 仓库里不会包含任何晚于其上次升级的新 refs。复盘明确指出：理想情况下，发布执行人应能构造一个"同步到上一 beta 版本、且不含任何更新 refs"的 Git 仓库，才能真正复现用户的升级环境。这条观察直接催生了 action item 中"为 flutter upgrade 增加隐藏的 --version 参数以精确模拟升级路径"的计划。

有趣的是，升级"分阶段、可续跑"的机制在今天的实现中已经相当成熟：当前 flutter upgrade 采用两阶段（first half / second half）的再入式设计——第一阶段完成版本比对、git reset --hard <revision> 与切渠道后，会通过 flutter upgrade --continue --continue-started-at <时间戳> 让新版工具接管第二阶段（precacheArtifacts 下载引擎产物、pub get 更新包、运行 flutter doctor）。相关参数 --force、--verify-only、--continue 等的定义见 upgrade.dart，硬重置逻辑见 attemptReset。

关键缺陷 5：推送权限与发布者信息不对称

• 执行发布的 @tvolkert 没有推送 HEAD:beta 的权限，因为 beta 在 GitHub 上是受保护分支。当天为了等权限授权白白损失了约 20 分钟（11:40→12:02）。
• 修复补丁 v0.1.4→v0.1.5 在发布次日推送，但除了订阅 flutter-dev 邮件列表的用户，其他人完全不知道有新升级可用——当时的 flutter 工具不会主动提示有新版。

这直接引出两条行动项：为 beta 建立独立的 GitHub 推送小组以管控权限；让 flutter 工具在存在新版本时主动提醒用户（issue #14920）。

关键缺陷 6：文档站同步 bug 与 Travis 在 beta 分支上的失败

• 为 beta 发布准备的文档站改动（PR #14606）存在 bug：主文档站上的 docs 永远不会被更新（issue #15002），且因 GitHub code review 自动折叠了高度相关的内容，该 bug 在代码评审阶段未被发现。结果主文档站自 2 月 13 日起就再没更新过。
• beta 分支推送后，Travis 随即因 #14975 开始失败。类似的失败此前在 master 上出现过，并已由 #14853 修复；但该失败在 beta 分支上的表现方式引发了困惑——团队一时难以判断 beta 发布是否真的存在问题，还是仅仅撞上了已知缺陷。

Action items：复盘沉淀的四类行动清单

原文把后续行动分为 Prevention（预防）、Mitigation（缓解）、Process（流程）、Fixes（修复）四类，全部落在实处，多数关联到具体 issue 或已完成实现。

Prevention（预防类）

行动项	Owner	Issue	状态
确保 Travis 测试 gallery 的可构建性	@xster	—	已完成（PR #14714）
在 dev 分支上于 Travis 与 AppVeyor 构建全部 examples	@xster	#15164	—
为 flutter upgrade 增加隐藏 --version 参数，让发布执行人能更好模拟升级路径	@tvolkert	#14970	—
channel 命令切换渠道前先 fetch 上游 refs	@tvolkert	#14893	已完成（PR #14896）

其中"channel 切换前先 fetch 上游 refs"即前文已对照的 channel.dart 现状。

Mitigation（缓解类）

行动项	Owner	Issue	状态
让 flutter 工具在有新升级可用时主动提醒用户	@tvolkert	#14920	—

Process（流程类）

行动项	Owner	状态
新增关于识别 bad builds 的 wiki 页面	@tvolkert	已完成（对应文档见 Bad-Builds.md）
向核心团队发邮件，提醒需要主动考虑把构建标记为 bad	@tvolkert	已完成
更新发布流程，明确要求验证 gallery 可构建、可运行	@tvolkert	已完成
更新发布流程：在发出任何公告或公开沟通前，beta 分支上的 Travis 必须全绿	@tvolkert	已完成
在 GitHub 上建立 beta 推送小组，管控可推送 beta 的人员	@Hixie	已完成
更新 beta 发布流程：候选 dev build 必须"可从 beta 分支当前指向的 dev build 成功升级到"	@tvolkert	已完成
在发布流程中加入：下载并安装上一 beta 对应 dev build 的打包归档，验证其能升级到最新发布	@gspencergoog	—

Fixes（修复类）

行动项	Owner	Issue	状态
修复文档站，使其在下次 beta 推送时正常更新	@tvolkert	#15002	已完成（PR #15003）
修复 create_test.dart 的 "package" 模板测试依赖：改为依赖 package:flutter_test 而非 package:test	@tvolkert	#14975	已完成（PR #14976）

与当前仓库的对照：这些机制今天长什么样

复盘文档是 2018 年的历史快照，但其中暴露的问题域在今天仓库中几乎都能找到对应的成熟实现，可作为理解渠道与升级机制的第一手源码素材。

渠道体系（Channels）。今天的 Flutter 官方渠道定义在 version.dart 中：master/main（最新开发分支）、beta、stable，按稳定性递增排列，并配有面向用户的描述文案（beta 为"每月更新，推荐有经验的用户"，stable 为"每季度更新，面向新用户与生产发布"）。kObsoleteBranches 中还保留了渠道迁移的历史痕迹——2021 年废弃的 dev 渠道会被自动过渡到 beta（version.dart）。

渠道操作命令。当前 channel.dart 支持：

• flutter channel：列出可用渠道（--all 会额外展示全部远程/本地分支）；
• flutter channel <name>：切换到指定渠道，切换前先 git fetch 拉取最新 refs，再决定 checkout 已有分支或创建 tracking 分支（--force 可丢弃本地改动强制切换）；切换完成后默认执行 precache 下载全部平台二进制产物（--cache-artifacts，默认为 true），并提示用户运行 flutter upgrade 以确保位于该渠道最新构建之上（channel.dart）。

渠道说明文档。用户视角的渠道选择、切换命令示例记录在 Flutter-build-release-channels.md：文档明确给出 flutter channel 的典型输出、切换后需运行 flutter upgrade 的完整流程，以及 master / beta / stable 各自的定位与适用人群。

Bad builds 标记体系。"发现严重问题时应把受影响构建区间标记为 bad"这一教训，今天已固化为可操作的三方协作流程，见 Bad-Builds.md：P0 级用户可见缺陷（排除工具链/基础设施回归）需登记到 bad builds 追踪表，记录起始 bad commit、受影响平台，由自动化（每 12 小时运行）根据 commit URL 推导对应 CL，修复合入后再登记结束 commit hash。这与复盘"若 build 被标记为 bad，团队对受影响区间的感知会前置很多"的判断一脉相承。

需要说明的是：复盘正文多次引用的 Release-process.md（含 "rolling the beta channel" 章节）在当前仓库的 docs/releases 目录下已不存在（该目录仅保留渠道、cherrypick、bad builds、质量与版本化等文档），因此本文对发布流程类行动项只保留其行动项事实，不指向失效路径。

可复用的复盘方法论

对读者而言，这篇 postmortem 的价值不止于 Flutter 历史本身，其复盘结构可以直接迁移到任何"按计划发布、却靠用户反馈才暴露缺陷"的场景：

1. 用精确时间线还原事实：以分钟为粒度记录"谁在何时做了什么、看到了什么"，避免事后归因时的记忆偏差——本文时间线就是后来者理解事故因果链的可靠索引。
2. 区分"孤立问题"与"普遍问题"：@timsneath 的问题被反复论证是否为 outlier，避免在统计噪声上叫停发布、也避免在真实系统缺陷上盲目发布。判断手段是尝试重构用户环境并复现。
3. 审视测试盲区：Bazel 内部构建 vs 外部 Gradle 构建的割裂说明——测试环境与真实用户环境若存在结构性差异，就会产生"内测全绿、上线即红"的错觉。
4. 把"用户升级路径"当作一等公民：验证发布时要模拟真实用户路径（老 beta → 新 beta），而不是团队自己舒服的"全新 clone → dev → 新版本"路径。
5. 坏构建主动标记 + 消息触达：工具/流程应主动把"哪个区间坏了""有新版可升级"告诉用户，而不是指望用户订阅邮件列表或自己刷 issue。

在 Flutter 仓库中继续深入可查阅：本复盘原文 Postmortem-Beta-1-Release.md、同期发布的渠道使用说明 Flutter-build-release-channels.md、坏构建标记流程 Bad-Builds.md，以及沉淀了对应修复的 channel.dart 与 upgrade.dart。源码中 git fetch、--track -b、no upstream configured 防御、两阶段再入式升级等实现细节，正是这篇 2018 年复盘所提教训在多年演进后的最终落点。