从 v1.0 到 5.3：基于 CHANGELOG.v1-5.md 复盘 Storybook 前五个主版本的演进脉络

CHANGELOG.v1-5.md 是 Storybook 仓库中归档 v1.0.0 至 5.3.7（2016 年至 2020 年 1 月）全部发布记录的单一文件，共 10000 余行、600 余个版本条目。本篇以该文件为核心，逐条复盘 v1、v2、v3、v4、v5 五个主版本的关键变更与发布节奏，并结合当前仓库中 CHANGELOG.md、MIGRATION.md 和 code/ 目录结构交叉印证，帮助你把这份历史档案变成可检索、可验证的演进时间线。

这份变更日志在仓库中的位置与体例

当前仓库（主干版本已进入 10.5.x，见 CHANGELOG.md 首行 ## 10.5.10）把历史发布记录拆分管理：

• CHANGELOG.v1-5.md：覆盖 v1.0.0 到 5.3.7 的完整历史，是本篇的解读对象；
• CHANGELOG.md：记录 10.x 近期版本；
• MIGRATION.md：各主版本间的破坏性变更与升级说明，5.0/5.2/5.3 条目在文中均被显式引用。

从文件体例看，这份变更日志有四个可复用的书写特征：

1. SemVer + 预发布通道分层：每个 ## 标题对应一个版本号，稳定版（如 ## 5.3.0）与预发布版（5.3.0-alpha.*、5.3.0-beta.*、5.3.0-rc.*）并列记录。以 5.3.0 为例，条目从 5.3.0-rc.14 (January 11, 2020) 一直回溯到 5.3.0-alpha.0，完整保留了 alpha → beta → rc → stable 的迭代链；
2. 按类别分组：每个版本条目下按 ### Features、### Bug Fixes、### Maintenance、### Dependency Upgrades 等小节组织，便于定位某一类改动；
3. 逐条挂 PR 编号：每条变更都附带 Pull Request 编号（例如 [#9538] 类引用），使任何一条记录都能追溯到具体代码评审，这是该档案“可验证”的关键；
4. 依赖升级折叠收纳：在 v3.0.0 等大版本中，依赖升级列表被包进 <details>/<summary> 折叠块（见 CHANGELOG.v1-5.md#L9333-L9352），正文保持可读性。

稳定版条目通常先给一段“高亮摘要”，再引导读者去翻对应的预发布条目。例如 5.3.0 条目开头即声明四大亮点并提示“5.3 contains hundreds more fixes, features, and tweaks. Browse the changelogs matching 5.3.0-alpha.*, 5.2.0-…”，原文为：Browse the changelogs matching 5.3.0-alpha.*, 5.3.0-beta.*, and 5.3.0-rc.*（CHANGELOG.v1-5.md#L54-L63）。

v1.x（2016）：奠定“开发工作台”基础能力

文件末尾记录了项目最早期的版本（CHANGELOG.v1-5.md#L10153-L10235）。这一阶段的变更以单条功能说明加 PR 编号为主，代表性条目包括：

• v1.10.0：加入搜索框（search box）、静态文件构建器（static file builder）、iframe 内自定义 head；同一版本还修复了“渲染前先 unmount”的问题（Fix: #81）；
• v1.10.2：静态构建支持自定义 head、改用相对 URL 以便托管在带路径前缀的位置（如 GitHub Pages）、用特性检测识别 SyntheticEvent（因为 UglifyJS 压缩类名后无法按类名检测）；
• v1.11.0：支持 React DevTools；
• v1.12.0：ActionLogger 增加清除日志按钮、增加 JSX 支持；
• v1.3.0：手动加载 .babelrc（修复 #41）、增加 npm run dev 开发脚本；
• v1.4.0 / v1.5.0：CLI 支持指定 config dir、支持大部分自定义 webpack 配置（PR64）；
• v1.8.0：故事间跳转（story linking）能力；
• v1.0.0：全文只有一句“Yeah!”，并紧随其后是 v1.1.0 的说明——“v1.0.0 was a mistake and it contains very old code”，这是理解早期版本号不连续的一个直接证据。

从这些条目可以确认：v1 阶段的核心工作是把“浏览组件”升级为“可搜索、可静态构建、可自定义 webpack 与 babel 的开发工作台”。

v2.0.0（2016-08-01）：默认构建链对齐 create-react-app

v2.0.0 条目（CHANGELOG.v1-5.md#L9867-L9879）说明其定位是“almost compatible with v1.x.x but defaults have been changed”，主要变更是把默认配置对齐 create-react-app：

• 引入基于 postcss 的 CSS loader；
• 引入 file-loader 处理图片等常见资源类型、url-loader 处理更小的媒体文件；
• 不再预构建 manager（Storybook UI）bundle；
• 保留 babel stage-0 preset 支持并增加 es2016 preset；
• 同步升级 @kadira/storybook-ui 到 v2.6.1 以消除部分 React 警告。

值得注意的是条目中出现的包前缀 @kadira/storybook-ui——这正是下一主版本要解决的品牌问题。

v3.0.0（2017-05-31）：社区化、Webpack 2 与 monorepo 改造

3.0.0 被明确标注为“first fully community-driven release”（CHANGELOG.v1-5.md#L9276-L9287），头部摘要列出了五项结构性变化：

• 从 @kadira 命名空间整体迁移到新的 Storybook 组织（GitHub、npm、docs 全线换名）；
• 升级至 Webpack 2；
• 切换到 monorepo 并重构包结构（PR #749、#1031，其中 #1031 标题为 “CHANGE folder structure && CHANGE package-names”）；
• 快照测试增加配置项（snapshotWithOptions、自定义 test 函数）；
• 增加 create-react-native-app 支持与 dev server HTTPS 选项。

其 Features / Bug Fixes / Maintenance 小节进一步确认了工程化细节：build-storybook 不再支持相对路径（#1058）、CLI 不再硬编码包版本改为查询 npm registry（#1079）、内置 addons（links、actions）被弃用改为不再默认引入（#1038）等。

与当前仓库的对应关系：从源码结构看，本仓库 code/ 目录下按 core/、renderers/、frameworks/、addons/、builders/、presets/、lib/ 分包的组织方式，与 v3 时期确立的 monorepo 包结构一脉相承。换言之，今天你看到的目录划分，其“第一块砖”就记录在 3.0.0 的这两条 PR 里。

v3.4.0（2018-03-30）：多框架 Storyshots 与 Storysource

3.4.0 的头部摘要（CHANGELOG.v1-5.md#L5709-L5721）给出五个重点：

• Polymer 2 支持（#2225）；
• Angular 与 Vue 的 storyshots（#2564）；
• addon-storyshots 支持图片快照（#2413）；
• 多故事层级（multiple story hierarchies，#2452）；
• 新增 addon-storysource：在 addon 面板中展示故事源码（#2885）。

Features 小节还包含若干后来长期沿用的机制：build-storybook 增加 watch 模式（#2866）、Full Control Mode 下将默认 webpack 配置作为第三个参数传入（#2796）、面向外部工具的 __STORYBOOK_CLIENT_API__（#3058）、addon-info 的代码示例复制按钮（#2713）等。可以看到 3.4 是“文档与测试类 addon 生态成型”的版本。

v4.0.0（2018-10-29）：Webpack 4 / Babel 7 与渲染器扩张

4.0.0 条目（CHANGELOG.v1-5.md#L4447-L4477）是全文信息密度最高的稳定版摘要之一，按领域列出：

• 构建工具：Webpack 4（#3148）、Babel 7（#3746）；
• 视图层：一次性新增 Ember、MarkoJS、Mithril、HTML snippets、Svelte、Riot 六个渲染器（#4237、#3504、#3244、#3475、#3770、#4070）；
• 移动端：移动端视图可用 ☰ 按钮切换 stories 面板（#3337）；React Native 移除 packager（#4261）、支持 on-device addons（#4381、#4327）；
• UI：主题定制（theming，#3628）；
• Core：Story parameters（#2679）、通用 addon decorators（#3555）、css-modules 支持（#4405）、start-storybook 首次编译完成即打开浏览器（#4149）、端口占用时提示替代方案（#4146）、无 CLI 的 Node API（#4344）；
• CLI：重命名为 sb（#4345）。

该条目同时指出：完整清单需查 4.0.0-rc.* 与 4.0.0-alpha.* 条目，并指向迁移文档（仓库中的 MIGRATION.md 即这份迁移指南的延续维护版本）。从源码结构看，本仓库 code/frameworks/ 下的 vue3-vite/、svelte-vite/、nextjs/ 等框架包，正是这一时期“渲染器矩阵”思路的继承与扩展。

紧随其后的 4.1.0（2018-12-12，CHANGELOG.v1-5.md#L4131-L4142）则以性能与兼容性为主题：manager/preview 拆分带来的性能优化与冷启动、重建提速（#4834）、React 全版本支持（#4808）、新增 CSSResources addon 动态增删 CSS（#4622）、基于 CRA 选择 babel presets/plugins（#4836）、react-scripts 的 TypeScript 支持（#4824）。

v5.0.0（2019-03-05）：全新 UI 与 URL 结构

5.0.0 条目（CHANGELOG.v1-5.md#L3337-L3348）列出了六项全新 UI 改进：

• 全新设计，支持浅色/深色主题；
• Canvas toolbar，快速访问 addons；
• 重做导航侧边栏与菜单；
• 重设计的 addons 面板（含可见性与方向的开关按钮）；
• 改进且可用户配置的键盘快捷键；
• 新 URL 结构，消除一长串查询参数。

同样，条目提示完整变更需回溯 5.0.0-alpha.* / beta.* / rc.* 条目，并从 4.x 升级需阅读迁移指南（MIGRATION.md）。

v5.1.0 的一个“事故记录”：条目正文只有一行“Publish failed”（CHANGELOG.v1-5.md#L2258-L2260）。这类失败发布记录（如 5.3.0-rc.2 的 “Failed NPM publish”）是变更日志的诚实体现——版本号占位但内容未发布，阅读时需注意不要把这些当作可用版本。

v5.2.0（2019-09-13）：DocsPage 与 CSF3

5.2.0 摘要（CHANGELOG.v1-5.md#L1234-L1243）列出四个关键词：

• DocsPage：零配置文档页；
• Component Story Format：故事文件成为可移植的 ES6 模块（即 CSF3，当前仓库文档中仍在使用这一格式）；
• Design System 最佳实践；
• Addon API：基于 hooks 的简化版 addon 开发 API。

这一版本奠定了此后多年“文档即组件页面”的产品形态。其预发布条目跨度极长（5.2.0-alpha.0 至 5.2.0-beta.48），是观察一个功能从 alpha 打磨到 stable 全过程的最佳样本。

v5.3.0（2020-01-11）：MDX 文档与 main.js 声明式配置

5.3.0 摘要（CHANGELOG.v1-5.md#L54-L63）给出四大亮点：

• 基于 MDX 的自定义文档；
• 多框架（React、Vue、Angular、Web Components、Ember）的 Docs；
• Web Components 框架支持；
• main.js 声明式配置。

其中“main.js 声明式配置”的实现基础，被记录在 5.3.0-rc.6 (December 31, 2019) 条目中：该版本说明这是对 main.js（所谓 tri-config）的“significant change”，将 presets/registers 合并进 addons 字段，大幅简化 addon 与 preset 的注册方式（CHANGELOG.v1-5.md#L142-L148）。这一设计直接演化为此后版本中 .storybook/main.* 的配置形态，也解释了 MIGRATION.md 中关于 main 文件必须为合法 ESM 等升级要求的历史渊源。

5.3 系列的稳定补丁版（5.3.1～5.3.7）则展示了典型的维护节奏：围绕 Core 的 addon/preset 检测、默认故事排序、HMR、legacy URL 修复，以及 Source-loader 对生成代码关闭 lint 等问题的小步修复（CHANGELOG.v1-5.md#L1-L52）。

如何使用这份历史变更日志

结合上文梳理出的体例，这份档案有三种实用读法：

1. 按功能溯源：当你要弄清某个机制（如 story parameters、docs 页、main.js 配置）是何时引入、如何演进时，直接在该文件中搜索关键词，再顺着 PR 编号理解引入动机。例如 “story parameters” 命中 4.0.0 摘要中的 #2679；
2. 按版本升级核对：从 4.x 或 5.x 旧版本升级时，先读对应稳定版摘要，再对照 MIGRATION.md 中相应章节的破坏性变更；变更日志回答“改了什么”，迁移指南回答“需要动什么”；
3. 按预发布链观察打磨过程：每个主版本都有完整的 alpha/beta/rc 序列，功能条目往往先在 alpha 中出现、在 rc 中修边界问题、在 stable 中定稿。例如 __orderedExports / __namedExportsOrder 这类 CSF loader 机制，就分别记录在 5.3.0-rc.0 与 5.3.0-rc.9 中，反映了 API 在定稿前的调整轨迹。

需要说明的适用前提：本文件是历史归档，其中描述的包名（如 @kadira/* 时期前缀）、配置形态（config.js/main.js 的早期字段）均不适用于当前 10.x 主干；当前版本的变更请以 CHANGELOG.md 为准，跨版本升级请以 MIGRATION.md 为准。但该文件作为 Storybook 前五个主版本的第一手发布记录，其条目与 PR 编号至今仍可逐条核验。