Storybook 启动性能基准测试实战：从 storybook dev 进程启动到首个 Story 渲染的度量方法论

Storybook 官方仓库将「启动时间基准测试」（startup benchmark）沉淀为一个可复用的 Agent 技能文档，定义了从 storybook dev 进程派生到浏览器中首个 Story 完成渲染的完整度量边界。读完本文，你将掌握如何搭建一个可重复执行的启动性能基准：划分 server / browser / total 三段耗时、在 preview 侧埋入渲染信号、用受控浏览器采集结果，并用分组统计（average / min / max / p95）对比不同 Storybook 版本或功能开关下的启动回归。

技能定位：这是一个"方法论 + 实施清单"

该文档在仓库中以 Claude Code / Agent 技能（skill）的形式存在，文件路径为 .claude/skills/storybook-startup-benchmark/SKILL.md。该文件仅包含一行引用指针，真正的内容位于 .agents/skills/storybook-startup-benchmark/SKILL.md。其 YAML frontmatter 声明了技能的元信息：

• name: storybook-startup-benchmark
• description：度量从派生 storybook dev 进程到浏览器中首个 Story 渲染完成的启动时间；适用于询问启动耗时、server-ready 时机、首帧渲染时机、启动回归、重复运行基准测试、对比不同 Storybook 版本或功能标志的场景
• allowed-tools: Bash, Read——技能只依赖 shell 命令与文件读取，说明它的设计目标是让 Agent 在任意具备 Node 环境的仓库中直接落地脚本，而不绑定特定测试框架

它的用途被明确界定为：构建或解释一个可重复执行的 Storybook 启动基准，核心产出是三段独立计时的度量结果。

三段式度量模型：server、browser 与 total

文档给出的第一段技术实质是对「启动时间」的边界定义，它将启动过程拆分为两个串行阶段与一个总量：

指标	计时区间	含义
server	进程派生 → Storybook 服务器可响应	CLI 启动、框架解析、编译管线准备、端口监听等纯服务端开销
browser	服务器可响应 → 首个 Story 渲染完成	页面加载、manager 引导、preview iframe 引导、首帧渲染的开销
total	进程派生 → 首个 Story 渲染完成	用户可感知的端到端启动时间

这个拆分的价值在于后续归因：文档在「解释结果」一节明确指出，server 增长说明回归很可能在服务端/构建侧，而 browser 增长说明问题在 manager 引导、preview 引导或首帧渲染侧。没有这个拆分，你无法回答「这个启动回归是服务端问题还是渲染问题」这类典型问题。

测量边界与关键规则

文档给出了明确的操作边界（Quick Start），任何基准脚本实现都应遵循：

1. 确认计时边界：
   • 在派生 storybook dev 进程之前立即开始计时；
   • 访问 Storybook 的 / 路径，而不是 iframe.html；
   • 在首个 Story mount 完成后再加一帧 requestAnimationFrame() 时停止计时。
2. 优先复用：先检查仓库中是否已有 benchmark 脚本，有则复用。
3. 若无现成脚本，创建一个 Node 脚本，满足以下四点：
   • 以 --no-open 参数启动 Storybook；
   • 等待服务器可响应；
   • 启动一个由脚本自己受控的浏览器；
   • 等待 preview 侧的渲染信号；
   • 打印 JSON 结果。
4. 支持 --repeat <count>，输出分组汇总统计。

文档同时给出了五条默认测量规则（除非用户明确要求否则一律遵循）：

• Start URL：/；
• 浏览器路径：走正常的 manager 页面，让 Storybook 自己去加载 preview iframe（模拟真实用户路径，而非绕过 manager 直接打 iframe）；
• 渲染信号：首个 preview story mount + 一次 requestAnimationFrame()；
• 浏览器启动：由外部 harness 启动浏览器，而不是让 Storybook 自己去开；
• 禁用自动打开：用 storybook dev --no-open 关掉 Storybook 自带的浏览器自动打开行为。

其中有一条原则性警告值得强调：不要只测量 CLI 输出。"服务器在监听"（server listening）不等于"首个 Story 已渲染"——前者只是 total 的一半，只测 CLI 就绪会把 manager/preview 引导与首帧渲染的全部开销从数据中抹掉，导致版本对比失真。

推荐实现一：preview 侧的渲染信号

要拿到「首个 Story 已渲染」这一时刻，必须有一个来自页面内部的信号，因为 harness 从外部 HTTP 探活只能证明服务器活着。文档推荐的做法是添加一个只运行一次的小型全局 preview decorator 或组件，在首个 story mount 时执行以下动作：

• 等待一次 requestAnimationFrame()（确保这一帧真正被合成/绘制，消除 mount 与首帧之间的微小空窗）；
• 设置一个全局变量，如 window.__sbStartupBenchmark；
• 在同源（same-origin）时把该值同步镜像到 window.top，让外层 manager 页面的 harness 也能读到；
• 可选地调用 performance.mark('sb:first-story-rendered')，这样信号还能被 Performance API 消费，与浏览器内置的性能工具打通。

推荐携带的 payload 结构：

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

firstStoryRenderedAt 用 performance.now() 记录渲染时刻，storyId 则让每次运行可以确认命中的是预期的首个 story——这在多 story 或路由不同的场景下是防呆手段。

推荐实现二：harness 脚本行为

文档对基准脚本（harness）给出了 8 步行为清单，覆盖了启动、采集与清理三个阶段：

1. 端口冲突快速失败：如果目标 Storybook 端口已被占用，立即报错退出（这是最常见的数据污染源，后文会再讲）；
2. 以 --no-open 派生 Storybook 进程；
3. 在派生之前立即开始计时（total 的起点）；
4. 对 Storybook URL 轮询 HTTP 就绪（server 区间结束、browser 区间开始）；
5. 启动受控浏览器访问 /；
6. 等待 preview 侧渲染信号（browser 区间结束）；
7. 打印 JSON 结果；
8. 清理阶段杀死整个派生的进程组（而不是只杀直接子进程），防止残留的 Storybook 子进程污染下一轮运行。

第 1 步与第 8 步是对应关系：前者防输入污染，后者防输出残留，共同保证 --repeat 下每轮都是干净的冷启动。

推荐实现三：重复运行与分组统计

单次测量无法区分「代码变慢了」和「这台机器今天抖了」，因此文档要求 --repeat N 支持，并规定输出三层内容：

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

文档给出的推荐汇总字段示例（JSON 结构）：

{
  "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"
  }
}

注意统计量是四元组：average / min / max / p95。这个组合不是随意选的——average 反映常见路径（common-case latency），p95 反映尾部延迟（tail latency），min/max 提供支撑边界。文档在「输出风格」一节进一步要求：报告时先讲 average 和 p95，min/max 作为辅助边界；并要明确指出回归影响的是常见路径延迟、尾部延迟还是两者兼有。同时有一条纪律：除非基准已经把 server 与 render 行为隔离开了，否则不要宣称根因——这与开头的三段式度量模型首尾呼应。

结果解释启发式

文档提供了四条把数字翻译成结论的启发式规则，这是该技能从「测量工具」升级为「诊断工具」的关键：

1. server 增长 → 回归大概率在服务端/构建侧（CLI 启动、框架解析、编译管线）；
2. browser 增长 → 回归大概率在 manager 引导、preview 引导或首帧渲染；
3. average 接近但 p95 显著增大 → 该特性更可能增加的是波动性或尾部延迟，而不是稳定地拖慢每次启动；
4. 新版 Storybook 关闭某特性时远快于旧版，但打开该特性后耗时回到旧版水平 → 说明该特性抵消（erases）了新版在启动上的改进。

第 4 条是功能开关（feature flag）对比实验的判读标准：它回答的不是「这个特性慢多少」，而是「这个特性是否吃掉了新版本的启动优化收益」。

常见陷阱与排查

文档列举了五个高频陷阱，每一条都直接对应数据失真：

• 基准端口上已有 Storybook 在运行——HTTP 探活会立刻命中旧实例，server 时间被人为压到接近零；
• Storybook 自动打开了另一个浏览器窗口——浪费资源、干扰受控浏览器，也可能抢占端口/内存；
• 直接测 iframe.html 而不是 /——绕过了 manager 引导路径，测出来的不是真实用户路径；
• 轮次之间残留子进程——残留进程占用端口与缓存，使后续轮次变成「温启动」；
• 把温重复运行（warm repeated runs）当成冷启动数据——磁盘缓存、编译缓存都会让非首轮次系统性偏快。

文档还给出了一条针对性排障指引：如果重复基准的 server.average 低得不真实（unrealistically low），第一个要检查的就是同一端口上的陈旧 Storybook 服务。这与 harness 清单第 1 步「端口占用快速失败」是同一问题的两面。

工具选择建议

• 优先使用纯 Node 脚本以保证可移植性，不绑定特定 E2E 框架；
• 对 Chrome 系浏览器，远程调试（remote debugging）是实际的受控通道——harness 通过它驱动浏览器、轮询全局变量；
• 如果对 Storybook CLI 的某个 flag 或行为有疑问，先获取当前版本的 Storybook 文档再下结论，避免基于过时的 CLI 语义写基准。

仓库中的相关佐证

从源码结构看，这个技能不是孤立的：

• 技能入口 .claude/skills/storybook-startup-benchmark/SKILL.md 是一行指针（@../../../.agents/skills/storybook-startup-benchmark/SKILL.md），内容实际维护在 .agents/skills/storybook-startup-benchmark/SKILL.md。这种「.claude 指向 .agents」的组织方式意味着同一份技能被多个 Agent 工具链共享，改动只需落在 .agents 一侧；
• 仓库同时存在 scripts/bench/ 目录，包含 bench-packages.ts、browse.ts、safe-args.ts、types.ts、utils.ts 与 bench.schema 等文件。从文件名可以推断，这是一套针对包级别的性能基准脚本，与本文的「启动」基准属于不同维度的性能测量——前者关注构建产物/包，后者关注 storybook dev 端到端启动。这也印证了文档「先检查仓库是否已有 benchmark 脚本、有则复用」这条 Quick Start 步骤的必要性：写新基准之前，应先弄清仓库已有工具链的边界。

适用前提小结

这套方法论的适用前提是：能够以编程方式派生 storybook dev 进程、能够控制一个浏览器实例、并允许在 preview 侧注入一个一次性渲染信号（全局 preview decorator）。它以「server / browser / total 三段拆分 + --repeat 分组统计」为核心契约，任何版本对比、功能开关实验或启动回归排查，只要遵守文中列出的测量规则（/ 入口、--no-open、外部受控浏览器、mount + 一帧 rAF 停止计时），其结果就可以横向可比；而任何偏离这些边界的测量（CLI 就绪即停、直连 iframe、复用端口上的旧实例），产出的数字都不应进入结论。