Storybook 4 迁移指南

本分步指南将帮助您迁移到 Storybook 4.0 (SB4)。

您可能在这里是为了了解 SB4 中的所有出色功能，并想知道如何升级现有项目。或者，您已经尝试过升级但未能成功。无论哪种情况，您都来对地方了。

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

1. 升级 Storybook 包
2. 如果您遇到问题，请处理 Webpack 4 / Babel 7 的相关问题
3. 处理插件和次要的破坏性变更

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

注意：React Native 是一个特殊情况，并且有自己的超棒指南。

第一步：包升级

首先要做的就是升级您的 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步。

第二步：Webpack/Babel 升级

如果第一步失败，并且您在浏览器中看不到 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 7，除非您的项目以某种方式与 Babel 6 绑定。这是未来，而且所有时髦的人都在这样做。

选项 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 预设和插件，您也需要将它们升级。Babel 是一个功能齐全的平台，它有自己的升级指南，您可以查阅以获得升级帮助。

选项 3：继续使用 Babel 6

如果您无法升级到 Babel 7，因为您正在使用某些特定于 Babel 6 的功能，您应该可以使用babel-loader 7 来实现向前兼容。

yarn add babel-loader@7

还要确保您的项目中有一个.babelrc文件，如果您选择此选项，您可能已经有了。以下是一个用于 React 项目的最小配置：

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

第三步：插件和“次要”的破坏性变更

如果您的 storybook 看起来运行正常，那么您已接近终点！以下还有一些您应该了解的事情。

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

1. 不依赖特定视图层的通用插件。
2. 通过 story 参数配置的插件装饰器。

通用插件

首先，让我们看看通用插件。这个 3.x 代码从一个特定于 React 的 API 导入 knobs 插件：

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

在 SB4 中，它变成：

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

更好，不是吗？而且修复起来很容易。有关更多信息，请参阅完整的迁移文档。

Story 参数

现在，让我们看看带有 story 参数的插件装饰器。SB4 引入了 story 参数，我们已更新所有核心插件以使用它们。

在 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' })

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

小的破坏性变更

除了更新您的插件外，还有一些小的破坏性变更您应该知道。如果其中任何一项适用于您的项目，它们应该只需要最小的更新即可修复。

这是一个清单，可以帮助您快速更新：

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

✅ 您是否使用addon-info？我们删除了addWithInfo。

✅ 您是否使用addon-knobs？我们更改了它的select行为以及它保存 URL 的方式。

✅ 您是否使用addon-storyshots？有一些 API 变更您应该知道。特别是，如果您使用 webpack 的require.context包含 stories，您将需要babel-plugin-require-context-hook。

✅ 您是否在 CI 中运行 storybook？start-storybook现在会弹出浏览器，但您可以使用--ci标志禁用此功能。

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

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

好了！这没什么大不了的，对吧？

完工！

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

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

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

— 来自 Storybook 团队的爱