Storybook 6 迁移指南

本分步指南将帮助您升级到 Storybook 6.0 (SB6)。

每年我们都会发布 Storybook 的主要版本。去年春天，发布了 Storybook 5.0，对用户界面进行了令人难以置信的改造。今年，我们彻底改进了 Storybook 的开发者体验。我们将其变成了一流的文档工具，并在此过程中彻底改革了配置和故事编写。

本指南将带您了解

1. 升级 Storybook 包
2. 处理破坏性更改
3. 更新到当前的最佳实践

我们假设您是从一个 5.0 项目升级，并会告诉您升级所需的所有信息。如果您一直在跟踪 5.x 版本（5.1/5.2/5.3），您可能会跳过一些步骤。如果您来自更早的 Storybook 版本，您可以参考 SB5 升级指南，然后再回来。

☝️ 步骤 1：包升级

第一件事是升级您的 Storybook 包，@storybook/*。您可以使用以下命令进行升级

npx sb@latest upgrade

然后尝试运行 Storybook

yarn storybook

如果浏览器打开并且一切看起来正常，您就完成了大部分工作，可以跳到步骤 3。

✌️ 步骤 2：破坏性更改

如果您没有看到您的 Storybook，是时候弄清楚是哪些破坏性更改让您受阻了。此版本是一个 semver 主版本，因此包含许多可能的陷阱。

查看终端和浏览器控制台中的错误/警告消息，应该会给您一些关于哪里出错的线索。

此外，这里有一份常见的升级问题清单

✅ 您使用 TypeScript 吗？现在它是零配置的 — 并且好得多！— 但您需要更新您的设置。

✅ 您是否使用层级分隔符控制侧边栏导航？我们在 6.0 中简化了这一点，并且有一个 codemod 来升级您的故事。

✅ 您使用 addon-info、addon-notes、addon-contexts 或 addon-centered 吗？如果是，这些在 6.0 中都已被弃用。

✅ 您使用 Create React App 吗？如果是，我们已将内置的 CRA 支持移至一个单独的包中。

✅ 您使用 addon-docs 吗？我们移除了框架特定的预设，将主题 API 与 Storybook 的主主题分开，移除了用于自定义的“槽位”概念，重命名了一些 DocBlocks，并更新了在 MDX 中嵌入 CSF 的最佳实践。请参阅文档升级说明获取详细信息。

✅ 您使用 addon-actions、addon-backgrounds、addon-knobs、addon-links 或 addon-queryparams 吗？如果是，我们为每个插件添加了预设，这些预设改进了插件的启动行为，但可能与您现有的设置冲突。阅读详情。

✅ 看到 core-js 依赖错误？这里有一个解决方法。

除了这份高级清单，我们在 MIGRATION.md 中详细记录了所有破坏性更改和注意事项。

如果您已经检查了这份清单和 MIGRATION.md，但仍然遇到错误，请尝试清除 node_modules 和您的锁定文件，然后重新安装。npm/yarn 有时需要额外的“推动”！

🤟 步骤 3：最佳实践

如果您的 Storybook 现在可以工作了，恭喜您！给自己点个赞吧。🎉 如果不行，请检查我们的 Github issues 或加入我们的 Discord。

现在您已经完成了基础工作，我们还建议您花一些时间将 Storybook 更新到当前的最佳实践。这些都不是严格必需的，但现在花时间去做是值得的。许多这些更改将在 SB7 中成为必需，我们正在积极改进并基于最新的最佳实践进行构建。

其中包括

✴️ 您是否使用 storiesOf 编写故事？升级到 组件故事格式 (CSF)。如果您想对文档进行更多控制，请选择 MDX。

✴️ 您使用 config.js 配置 Storybook 吗？Main.js 声明式配置，在 5.3 中引入，是一个巨大的改进，并强烈推荐使用。升级到main.js。

✴️ 您使用 TypeScript 吗？如果是，请升级到我们新的零配置 TypeScript 设置，以获得改进的性能和更好的自动生成文档。

✴️ 想要一个精心策划、符合最佳实践的 Storybook 插件设置？考虑升级到 Essentials，这是朝着完全零配置 Storybook 迈出的重要一步。

✴️ 您的组件是否已文档化？添加 Storybook Docs 以获取所有故事的自动生成最佳实践文档。

✴️ 有一个大型 Storybook，想将来自多个框架的故事文档化到一个 Storybook 中，或者需要将多个 Storybook 合并为一个？升级到 Storybook 组合。

✴️ 您使用 addon-knobs 吗？Storybook Controls 是 Knobs 的无代码替代品，可根据您的组件属性自动生成控件。这里是如何将您的故事迁移到控件。

✴️ 您使用全局参数或装饰器吗？在 6.0 中，您应该以声明方式添加它们；我们已弃用addParameters/addDecorator。

🖖 步骤 4：长寿并繁荣

希望到此为止您已成功升级到 SB6。如果是，恭喜您，欢迎来到世界上最好的开发、测试、文档化和探索您的 UI 组件的方式！！！🎉🎉🎉

如果您在完成本指南时遇到问题，或者已经完成了指南但仍然有问题，请执行以下步骤

1. 在我们的 Github issues 中搜索您的问题 — 可能其他人也遇到了同样的问题。
2. 创建一个新 issue 描述您的问题，最好附上一个公共仓库的链接，以便我们可以重现问题。
3. 加入我们的公共 Discord 并在 #support 频道提问。我们是一个友好的社区，希望帮助您完成升级。