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 和你的 lockfile 并重新安装。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 Composition。

✴️ 你使用 addon-knobs 吗？Storybook Controls 是 Knobs 的无代码继任者，它基于你的组件 props 自动生成控件。这是如何将你的故事迁移到控件。

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

🖖 步骤 4：生活幸福，万事如意

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

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

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