发布与迁移

相关源文件

• .gitignore
• CHANGELOG.md
• CONTRIBUTING.md
• LICENSE
• MIGRATION.md
• README.md
• code/addons/docs/src/preset.ts
• code/builders/builder-vite/src/optimizeDeps.ts
• code/renderers/server/preset.js
• code/renderers/server/src/preset.ts
• docs/versions/latest.json

本页面介绍 Storybook 的软件包如何发布、版本控制以及用户如何升级版本。它涵盖了从开发到发布的整个流程，以及帮助用户在主要版本之间过渡的全面迁移系统。

概述

Storybook 维护着一个双重版本管理系统：一个用于发布新版本的结构化发布流程，以及一个用于升级现有项目的自动化迁移系统。发布流程包括多个渠道（alpha、beta、RC、stable）以及全面的文档，而迁移系统则为重大更改提供了自动化的 codemods 和详细指南。

来源： CHANGELOG.md1-304 MIGRATION.md1-440

版本管理策略

Storybook 遵循 语义化版本，格式为 X.Y.Z

版本组件	描述	迁移影响	示例
主版本号 (X)	破坏性变更	需要迁移指南和自动化迁移	8.x → 9.0.0
次版本号 (Y)	新功能	向后兼容，可选迁移	9.0.0 → 9.1.0
修订号 (Z)	Bug修复	无需迁移	9.0.0 → 9.0.1

当前版本跟踪

当前稳定版本跟踪在 docs/versions/latest.json 中，其中包含

主版本发布（例如 9.0.0）包含重大的架构性更改

• 捆绑包大小轻了 48%
• 组件测试集成
• 软件包整合（将插件移至核心）
• 特定于框架的重大更改

来源： docs/versions/latest.json1-2 CHANGELOG.md38-54 MIGRATION.md3-47

发布渠道与迁移支持

Storybook 使用多个发布渠道，并提供相应的迁移支持

渠道	NPM 标签	迁移支持	目的
Alpha	alpha	有限的自动化迁移	早期测试，可能不稳定
Beta	beta	部分自动化迁移	功能完整但可能存在 bug
Release Candidate	rc	完整的自动化迁移	在最终发布前的稳定化阶段
稳定	最新版	完整的迁移指南	生产就绪，提供完整的升级路径

发布渠道迁移流程

来源： CHANGELOG.md54-55 MIGRATION.md112-133

发布与迁移工作流程

集成迁移的发布工作流程

用户升级工作流程

来源： CHANGELOG.md142-148 MIGRATION.md112-133 README.md164-196

迁移系统架构

自动化迁移基础设施

Storybook 包含一个全面的自动化迁移系统，可处理常见的升级场景

CLI 迁移命令

主要自动化迁移示例（9.0 版本）

从 CHANGELOG 和 MIGRATION 文件来看，主要的自动化迁移包括

迁移类型	描述	代码参考
软件包整合	将必要的插件移至核心	@storybook/addon-actions → storybook/actions
框架更新	渲染器到框架迁移	@storybook/react 配置更新
配置更改	更新 main.js 结构	.storybook/main.js 修改
依赖移除	移除已弃用的软件包	移除 @storybook/addon-essentials

来源： CHANGELOG.md127-133 MIGRATION.md12-26

发布文档结构

MIGRATION.md 文件遵循层级结构

重大变更管理

主版本发布包含系统的重大变更文档

9.0.0 重大变更示例

• 软件包整合：核心插件移至核心包
• 框架更改：基于渲染器的配置 → 基于框架的配置
• 依赖更新：不再支持 Node.js < 20，TypeScript < 4.9
• API 移除：移除已弃用的 API，提供迁移路径

来源： MIGRATION.md4-47 CHANGELOG.md100-227

发布文档系统

CHANGELOG.md 结构

变更日志遵循结构化格式，包含特定部分

发布格式示例 (9.0.0)

## 9.0.0

#### Storybook 9.0 is here

This is a huge release focused on testing and bundle size.

- Component testing
  - 👆 Interactions
  - ♿️ Accessibility  
  - 👁️ Visual changes
  - 🛡️ Coverage
- 🪶 48% lighter bundle
- 🏷️ Tags-based organization
- 🌐 Story globals
- 🏗️ Major upgrades: Svelte, Next, React Native, Angular

Please checkout our [Migration guide](https://storybook.org.cn/docs/9/migration-guide)

每个条目包含：

• 版本号和发布类型
• 高级功能摘要
• 详细变更列表，包含 PR 链接
• 迁移指南参考
• 贡献者致谢

来源： CHANGELOG.md38-304

MIGRATION.md 组织

迁移文档的组织是层级化的

迁移示例（软件包整合）

### Essentials Addon: Viewport, Controls, Interactions and Actions moved to core

The following addons are now part of the core Storybook bundle:
- @storybook/addon-viewport → storybook/viewport
- @storybook/addon-controls → storybook/controls  
- @storybook/addon-actions → storybook/actions
- @storybook/addon-interactions → storybook/interactions

**Automigration**: This change is handled automatically by the upgrade command.

来源： MIGRATION.md12-18 MIGRATION.md100-103

技术实现细节

软件包架构演进（9.0 整合）

9.0 版本显著重构了软件包架构

9.0 之前（分散的软件包）

9.0 之后（整合的核心）

迁移命令实现

升级系统使用特定的 CLI 命令和检测逻辑

CLI 升级检测流程

构建系统和依赖项

构建过程管理复杂的依赖关系

软件包构建顺序

1. 核心软件包：storybook（整合包）
2. 框架软件包：@storybook/react, @storybook/vue3, 等
3. 独立插件：@storybook/addon-docs, @storybook/addon-a11y
4. 构建器软件包：@storybook/builder-vite, @storybook/builder-webpack5

Vite 优化依赖

构建系统包含针对不同软件包类型的特定优化

来源： CHANGELOG.md100-224 code/builders/builder-vite/src/optimizeDeps.ts11-150

预设系统集成

发布流程必须考虑预设配置

来源： code/addons/docs/src/preset.ts154-194

发布后活动

发布成功后

1. Storybook 网站将更新新的文档
2. 发布公告将发布在
   • Twitter/X (@storybookjs)
   • Discord 社区
   • 重要发布的博客文章
   • 主要功能相关的 YouTube 视频

来源： README.md157-163

管理重大变更

对于带有重大变更的主版本

1. 在 MIGRATION.md 中创建详细的迁移指南
2. 代码示例展示如何从先前版本更新
3. 在次版本发布中添加弃用警告，然后移除
4. 创建 codemods 以尽可能自动化迁移

来源： MIGRATION.md1-43

总结

Storybook 的发布流程通过以下方式确保高质量的发布：

• 结构化的开发和测试工作流程
• 多个发布渠道以逐步稳定
• 对变更进行全面文档化
• 语义化版本控制以传达影响
• 自动化的构建和发布流程

有关如何为 Storybook 开发做出贡献的信息，请参阅 开发工作流程 wiki 页面。