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，并更新了将CSF嵌入MDX的最佳实践。请参阅Docs升级说明以获取详细信息。

✅ 你使用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吗？5.3中引入的Main.js声明式配置是一个巨大的改进，也是强烈的推荐。升级到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. 创建一个新问题来描述你的问题，最好附上一个公开仓库的链接，我们可以从中重现这个问题。
3. 加入我们的公共Discord，并在#support频道提问。我们是一个友好的社区，希望能帮助你完成升级。