Storybook 启动耗时基准测试实战：从 `storybook dev` 进程启动到首个 Story 渲染的可复现测量方法论

本文基于 Storybook 仓库中的技能定义文档 .agents/skills/storybook-startup-benchmark/SKILL.md，完整阐述一套可重复执行的 Storybook 启动基准测试方法：如何划定 server / browser / total 三级计时边界、如何在 preview 侧埋点捕获"首个 story 渲染完成"信号、如何编写支持重复跑分与分组统计的测试 harness，以及如何正确解读 p95 与均值差异来定位启动回归发生在构建侧还是渲染侧。读完本文，你可以为任意 Storybook 项目建立可对比、可回归检测的启动时间度量体系，并在不同版本或特性开关之间做出可信的性能结论。

三级计时边界：server、browser 与 total

启动基准测试的第一步是明确"启动完成"的定义。技能文档将启动耗时拆分为三个可独立观测的阶段：

阶段	起点	终点	含义
server	进程 spawn 前	Storybook 服务器开始响应 HTTP 请求	覆盖配置加载、框架初始化、构建管线就绪
browser	服务器响应	首个 story 在浏览器中渲染完成	覆盖 manager 启动、preview iframe 加载、docgen 与首个 story 挂载
total	进程 spawn 前	首个 story 渲染完成	用户视角的完整冷启动耗时

技能文档特别强调一条核心原则（见 SKILL.md "Measurement Rules" 一节）：

Do not measure only CLI output. Server listening is not the same as first story rendered.

即不能只看 CLI 打印 "Storybook started" 就算启动完成——服务器端口可访问只说明 server 阶段结束，用户真正可用的时刻是浏览器里第一个 story 挂载到 DOM 之后。这也是整个方法论与"端口探测脚本"类粗糙测量的本质区别。

测量边界的三条硬性约定

在进行任何测量前，技能文档要求先确认以下边界（"Quick Start" 第 1 步），这些约定直接决定测量结果是否可对比：

1. 计时起点：在 spawn storybook dev 进程之前立即开始计时，而不是在进程 spawn 之后；
2. 起始 URL：打开 Storybook 的 /（正常 manager 页面），不是 iframe.html；让 Storybook 自己加载 preview iframe，这样 browser 阶段才包含 manager 与 preview 的完整协调成本；
3. 计时终点：首个 preview story 完成 mount 再加一帧 requestAnimationFrame()，以此排除挂载回调触发但画面尚未真正绘制完成的边界误差。

同时，默认约定还包括：

• 浏览器由外部 harness 启动并控制，而不是让 Storybook 自己打开浏览器窗口；
• 用 storybook dev --no-open 关闭 Storybook 的自动打开行为。

这一点在源码中可以得到印证：--no-open 是 core CLI dev 子命令的真实选项，定义于 code/core/src/bin/core.ts：

command('dev')
  .option('-p, --port <number>', 'Port to run Storybook')
  // ...
  .option('--smoke-test', 'Exit after successful start')
  .option('--ci', "CI mode (skip interactive prompts, don't open browser)")
  .option('--no-open', 'Do not open Storybook automatically in the browser')

值得注意的是同一处还定义了 --smoke-test（启动成功后立即退出）和 --ci（CI 模式，跳过交互提示且不打开浏览器）。从源码结构看，--smoke-test 适合验证服务器侧启动健康度，但它以"启动成功"而非"首屏渲染"为终点，因此只覆盖 server 阶段；而本方法论的 harness 需要自行完成完整的 browser 阶段观测，不能以 --smoke-test 代替。

至于浏览器打开行为的底层实现，位于 code/core/src/core-server/utils/open-browser/opener.ts：其测试 opener.test.ts 覆盖了 BROWSER 环境变量（包括 BROWSER=none）的处理逻辑。因此在 CI 或无头环境中，除了 --no-open，也可以依赖 BROWSER=none 作为双保险，防止 Storybook 意外拉起一个脱离控制的浏览器窗口污染计时。

第一块拼图：Preview 侧的渲染信号

浏览器端需要在"首个 story 真正渲染出来"的瞬间发出信号，供外部 harness 监听。技能文档推荐的做法是添加一个小型全局 preview decorator 或组件，在首个 story 挂载时执行一次：

1. 等待一次 requestAnimationFrame()；
2. 设置一个全局值，如 window.__sbStartupBenchmark；
3. 在同源（same-origin）条件下，把该值镜像到 window.top（manager 与 preview iframe 之间的桥接）；
4. 可选地调用 performance.mark('sb:first-story-rendered')，便于后续在 Performance 面板中交叉验证。

推荐的信号负载结构为：

{
  firstStoryRenderedAt: performance.now(),
  storyId: id
}

这里的设计细节值得展开：

• 用 performance.now() 而不是 Date.now()，因为前者是高精度单调时钟，且与 harness 侧通过页面上下文读到的时间轴可对齐；
• 记录 storyId 使得结果可以追溯"到底是不是预期的首个 story 被渲染"，防止路由或默认 story 变化导致的假阳性；
• 镜像到 window.top 是因为 preview iframe 与 manager 同源时，harness 从顶层文档读取全局值比深入跨 frame 查找更稳定；
• 多等一帧 requestAnimationFrame() 的意义在于：story 挂载（mount 回调执行）不保证像素已上屏，一帧动画帧之后才是浏览器完成绘制的合理近似。

第二块拼图：Harness 的八步标准流程

技能文档（"Recommended Implementation" 一节的 "Harness behavior"）为基准测试脚本规定了完整的执行顺序：

1. Fail fast：若目标 Storybook 端口已被占用，立即失败退出——而不是等一个不存在的"新"服务器启动；
2. 以 --no-open 参数 spawn Storybook 进程；
3. 在 spawn 之前开始计时（对应 total 起点）；
4. 轮询等待 Storybook URL 的 HTTP 就绪（对应 server 终点）；
5. 启动受控浏览器，访问 /；
6. 等待 preview 侧的渲染信号（对应 browser 终点与 total 终点）；
7. 打印 JSON 格式结果；
8. 清理阶段杀死整个 spawn 出的进程组（process group），防止 Storybook 的子进程（如 builder 的 watch 进程）在轮次之间残留。

第 1 步和第 8 步是保证可重复性的关键：技能文档在 "Common Pitfalls" 中明确指出，"已有 Storybook 正在运行占用基准端口"和"子进程在多次运行间存活"是最常见的两类污染源；并给出了一条具体的排查经验——

If a repeated benchmark reports unrealistically low server.average, first check for a stale Storybook server on the same port.

即如果重复跑分中出现"低得不可思议"的 server 均值，首先怀疑端口上残留了一个旧的、已经热好的 Storybook 服务，此时测到的其实是热服务的响应时间，而非冷启动耗时。

重复跑分：--repeat N 与分组统计

单次测量没有统计意义。技能文档要求 harness 支持 --repeat <count> 参数，并在输出中提供：

• 每次运行的明细结果（per-run results）；
• 按 server、browser、total 分组的汇总统计；
• 人类可读的时长格式（如 5.2s、2m15s），而不是裸的毫秒字段名。

推荐的汇总字段结构如下（直接摘自 SKILL.md）：

{
  "server": {
    "average": "5.2s",
    "min": "4.8s",
    "max": "6.1s",
    "p95": "6.0s"
  },
  "browser": {
    "average": "1.9s",
    "min": "1.6s",
    "max": "2.4s",
    "p95": "2.3s"
  },
  "total": {
    "average": "7.1s",
    "min": "6.6s",
    "max": "8.2s",
    "p95": "8.1s"
  }
}

注意示例数据自身的语义：total 的均值（7.1s）恰好约等于 server（5.2s）+ browser（1.9s），说明两阶段是串联关系，total 并不包含并行的额外成分。这种"三组同构字段"的输出格式让后续用脚本对比不同分支、不同版本的基线数据变得非常直接——每个阶段独立可比。

结果解读：如何把数字映射回代码层面的嫌疑

"Interpretation Guidance" 一节给出了一组将统计变化映射到根因方向的启发式规则，这也是三级拆分的直接价值所在：

• server 变大 → 回归大概率在服务器/构建侧（配置解析、框架初始化、构建管线）；
• browser 变大 → 回归大概率在 manager 启动、preview 启动或首个 story 渲染环节；
• 均值接近但 p95 明显增大 → 该特性更可能是增加了波动性或尾延迟，而不是普遍变慢；
• 新版本不带某特性时显著快于旧版本，但开启该特性后又回到旧版本水平 → 可以推断该特性"抵消"（erases）了新版本带来的启动优化收益。

最后一条对应典型的 A/B 特性开关实验：用 --repeat N 跑三组（旧版本、新版本关闭特性、新版本开启特性），即可定量回答"这个特性是否吃掉了启动优化"。

同时文档在 "Output Style" 一节约束了汇报纪律：先报 average 与 p95，min/max 只作为辅助边界；明确指出回归影响的是常见路径延迟（common-case）、尾延迟还是两者皆有；除非基准测试本身隔离了 server 与 render 行为，否则不要断言根因——即基准测试的职责是定位"问题在哪一侧"，而不是替代代码级排查。

常见陷阱清单

技能文档 "Common Pitfalls" 列出的五类陷阱，按危害程度整理如下：

1. 端口上已有 Storybook 实例在跑 —— 测到的是热服务的响应，server 会低得离谱；
2. Storybook 自动打开了一个独立浏览器窗口 —— 未用 --no-open 时，多出的窗口会争抢资源且不受 harness 控制；
3. 直接测量 iframe.html 的加载 —— 绕过了 manager，browser 阶段被系统性低估，且与"用户打开 / 的真实体验"不可比；
4. 轮次之间残留子 Storybook 进程 —— 必须由 harness 杀死完整进程组（呼应八步流程第 8 步）；
5. 把温热的重复运行当成冷启动数据 —— 磁盘缓存、依赖预构建等温态因素会让后续轮次偏快，解释结果时必须区分首轮与后续轮次。

工具选型：为什么是普通 Node 脚本

"Tooling Notes" 一节给出了实现层面的三条建议：

• 优先使用纯 Node 脚本以保证可移植性——不绑定特定测试框架或 CI 环境；
• 对 Chrome 系浏览器，远程调试协议（remote debugging）是实际控制浏览器的实用通道——harness 通过它打开页面、轮询 window.__sbStartupBenchmark、读取 performance 数据；
• 若对 Storybook CLI 的某个 flag 或行为存疑，先查当前版本的 Storybook 文档再写测量代码。

最后，需要区分仓库内已有的另一类基准设施：scripts/bench/ 目录（如 bench-packages.ts）基准的是各包的安装体积与依赖数量（self size、dependency size、dependency count，结果写入 BigQuery 并做分支对比），而非启动耗时。技能文档 Quick Start 第 2 步要求"先检查仓库是否已有 benchmark 脚本、可复用则复用"，其前提是确认已有脚本测的是同一维度——体积基准与启动时间基准的边界完全不同，不能互相顶替。

适用场景速查

该技能文档的触发条件（"Example Triggers"）本质上定义了这套方法论的适用问题域，当遇到以下类型的问题时，应套用本文流程：

• "如何测试 Storybook 的启动时间？"
• "从 storybook dev 到首个 story 渲染，帮我测一下。"
• "对比开/关某个特性 flag 时的 Storybook 启动差异。"
• "跑 20 次启动测量并汇总平均数。"
• "这次启动回归是服务器侧还是渲染侧？"

只要问题落在"启动耗时、server-ready 时机、首 story 渲染时机、启动回归定位、版本/特性对比"这五个概念上，就可以直接复用本文的三级边界、preview 信号、八步 harness 与分组统计方案，而不必重新设计测量口径——这正是把测量方法固化为团队技能（skill）文档的价值所在：同一套边界定义，让不同人、不同时间跑出的数字天然可比。