Storybook 4 迁移指南

这份循序渐进的指南将帮助您迁移到 Storybook 4.0 (SB4)。

您可能来到这里是因为听说 SB4 中有许多很棒的新特性，并想了解如何升级现有项目。或者是因为您已经尝试升级但未能成功。无论哪种情况，您都来对了地方。

SB4 中最大的破坏性变更包括从 Webpack 3 升级到 4，以及从 Babel 6 升级到 7。因此，我们将引导您完成以下步骤：

1. 升级 Storybook 包
2. 处理可能遇到的 Webpack 4 / Babel 7 问题
3. 处理插件和一些小的破坏性变更

如果本指南对您没有帮助，我们也在底部提供了后续步骤——我们有一个很棒的社区随时准备为您提供帮助。

注意：React Native 有其特殊性，并有自己的超棒指南。

步骤 1：包升级

首先要做的就是升级您的 Storybook 包，即 @storybook/*。如果您使用 yarn，可以像这样进行交互式升级：

yarn upgrade-interactive --latest

或者如果您使用 npm，这个命令可以达到目的：

npx npm-check-updates '/storybook/' -u && npm install

注意：Storybook 目前需要 React 16.3 及以上版本。如果您正在开发 React 组件，这意味着您需要升级到 16.3 或更高版本才能使用 Storybook 4.0。如果您将 Storybook 用于非 React 项目，则可能无需担心这一点。

更新：我们已更新 Storybook 4.1，恢复了对 React 15.x 的兼容性。团队加油！

如果您运行的是旧版本的 React，将收到以下错误：

core.browser.esm.js:15 Uncaught TypeError: Object(...) is not a function    at Module../node_modules/@emotion/core/dist/core.browser.esm.js (core.browser.esm.js:15)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Module../node_modules/@emotion/styled-base/dist/styled-base.browser.esm.js (styled-base.browser.esm.js:1)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Module../node_modules/@emotion/styled/dist/styled.esm.js (styled.esm.js:1)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Object../node_modules/@storybook/components/dist/navigation/MenuLink.js (MenuLink.js:12)

然后尝试运行 Storybook：

yarn storybook

如果浏览器打开并且一切看起来正常，那您就差不多完成了，可以直接跳到步骤 3。

步骤 2：Webpack/Babel 升级

如果步骤 1 失败并且您在浏览器中看不到 Storybook 运行，下一步就是找出原因。一个可能的罪魁祸首是 Storybook 对 Babel 7 的升级。使用 Babel 6 并会导致中断的常见项目类型包括：create-react-app v1 (CRA1) 项目、NextJS 6 项目和 Gatsby v1 项目。

但这可能有很多原因，所以让我们来找出原因。如果您在终端中看不到错误消息，请检查浏览器控制台中的错误消息。如果您的项目使用 Babel 6，您会在控制台上看到典型的 Babel 错误如下：

{ Error: Cannot find module 'babel-loader/package.json' 
   ... long stack trace
}

如果您的项目正在运行 Babel 6，您有几个选择：

1. 升级您的项目（例如 CRA 1 升级到 2，Next 6 升级到 7，或 Gatsby 1 升级到 2）
2. 不升级您的项目，但升级 Babel
3. 继续使用 Babel 6 并依赖 Babel 的向后兼容性。

除非您的项目因某种原因必须绑定到 Babel 6，否则我们建议升级到 Babel 7。这是未来的趋势，所有走在前面的人都在这样做。

选项 1：升级您的项目

假设您正在使用一个使用 Babel 6 的框架（例如 CRA1、Next6 或 Gatsby1）。为了获得 Storybook 4 的兼容性，最好的办法是将您的项目升级到最新版本，该版本使用 Babel 7。Web 框架在不断改进，所以何不趁此机会升级到最新最棒的版本？

为此，请确认该项目类型存在使用 Babel 7 的新版本。然后按照项目特定的升级说明进行操作。为了节省您的时间，这里提供了 CRA/Next/Gatsby 的升级链接：

• 从 CRA 1 升级到 2
• Next 7 发布公告
• Gatsby：从 v1 迁移到 v2

注意：据我们所知，Gatsby v1 无法与 SB4 配合使用，因此升级到 v2 是您的最佳选择。

选项 2：仅升级到 Babel 7

如果由于某种原因无法升级您的项目，您也应该可以通过以下命令在现有项目中仅升级到 Babel 7：

yarn remove babel-core babel-runtime
yarn add @babel/core babel-loader --dev

如果您使用 babel presets 和 plugins，您也需要升级它们。Babel 是一个功能齐全的平台，并且有其自己的升级指南，您可以查阅该指南以获取升级帮助。

选项 3：继续使用 Babel 6

如果您无法升级到 Babel 7 是因为使用了某些 Babel 6 特有的功能，您应该可以使用 babel-loader 7 来获得向前兼容性：

yarn add babel-loader@7

此外，请确保您的项目中有 .babelrc 文件，如果您选择了此选项，您很可能已经有了。这是一个适用于 React 项目的极简示例：

{ "presets": ["env", "react"] }

步骤 3：插件和“次要”的破坏性变更

如果您的 Storybook 似乎运行正常，那您就快完成了！这里还有一些您应该了解的事情。

如果您使用了任何插件，SB4 大幅改进了插件的便捷性。旧的 API 仍然可用，但您会收到弃用警告，花几分钟时间升级是值得的。改进包括：

1. 不与特定视图层绑定的通用插件。
2. 通过故事参数配置的插件装饰器。

通用插件

我们首先来看看通用插件。这是 3.x 版本中从针对 knobs 插件的 React 特定 API 导入的代码：

import { number } from “@storybook/addon-knobs/react”;

在 SB4 中，它变成了：

import { number } from “@storybook/addon-knobs”;

更好，对吧？而且修复起来也很简单。更多信息请参阅完整的迁移文档。

故事参数

现在我们来看看使用故事参数的插件装饰器。SB4 引入了故事参数，并且我们已经更新了所有核心插件来使用它们。

在 3.x 版本中，使用插件是通过类似包装函数的方式实现的：

storiesOf('My component', module)
  .add('story1', withNotes('some notes')(() => <Component ... />))
  .add('story2', withNotes('other notes')(() => <Component .../>))

现在在 4.0 版本中，它变成了：

// .storyook/config.js (global decorator, local also supported)
addDecorator(withNotes)

// Component.stories.js
storiesOf('My component', module)
  .add('story1', () => <Component />, { notes: 'some notes' })
  .add('story2', () => <Component />, { notes: 'other notes' })

故事参数直接对应旧的 withX 参数，因此迁移代码很容易。更多信息请参阅完整的迁移文档。

小的破坏性变更

除了更新您的插件，还有一些小的破坏性变更您应该了解。如果这些变更中的任何一个适用于您的项目，修复它们应该只需要极少的更新。

这是一个快速更新的清单：

✅ 您使用键盘快捷键吗？我们在 SB4 中改进了它们。

✅ 您使用 addon-info 吗？我们已经移除了 addWithInfo。

✅ 您使用 addon-knobs 吗？我们改变了它的 select 行为，并且也改变了它保存 URL 的方式。

✅ 您使用 addon-storyshots 吗？有几处您应该了解的 API 变更。特别是如果您使用 webpack 的 require.context 包含故事，您将需要 babel-plugin-require-context-hook。

✅ 您在 CI 中运行 storybook 吗？现在 start-storybook会弹出一个浏览器，但您可以使用 --ci 标志禁用它。

✅ 您使用 Typescript 和 ts-loader 吗？如果是，您可能需要将其升级到支持 webpack 4 的 4.0 后版本。

✅ 您使用 getstorybook CLI 吗？我们改进了 CLI，现在您可以使用 sb init 初始化一个新项目。

瞧！是不是没那么难？

就这些了！

希望至此您已成功升级到 SB4。如果是这样，恭喜您并欢迎来到组件开发的未来！

如果您在按照本指南操作时遇到问题，或者按照本指南操作但仍然存在问题，请采取以下步骤：

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

— Storybook 团队致以 ❤️