常见问题

以下是一些常见问题的答案。如果你有问题，可以在我们的 GitHub 讨论 中提问。

¥Here are some answers to frequently asked questions. If you have a question, you can ask it in our GitHub discussions.

错误：没有 angular.json 文件发现

¥Error: No angular.json file found

Storybook 可以设置为单项目和多项目 Angular 工作区。要为项目设置 Storybook，请在 angular.json 文件所在的工作区根目录运行 npx storybook@latest init。在初始化期间，将创建 .storybook 文件夹并编辑 angular.json 文件以添加所选项目的 Storybook 配置。在根级别运行命令很重要，以确保 Storybook 正确检测所有项目。

¥Storybook can be set up for both single-project and multi-project Angular workspaces. To set up Storybook for a project, run npx storybook@latest init at the root of the workspace where the angular.json file is located. During initialization, the .storybook folder will be created and the angular.json file will be edited to add the Storybook configuration for the selected project. It's important to run the command at the root level to ensure that Storybook detects all projects correctly.

我如何退出 Angular Ivy？

¥How can I opt-out of Angular Ivy?

如果你在使用 Angular Ivy 时遇到问题，你可以在 main.js 中停用它：

¥In case you are having trouble with Angular Ivy you can deactivate it in your main.js:

export default {
  stories: [
    /* ... */
  ],
  addons: [
    /* ... */
  ],
  framework: {
    name: '@storybook/angular',
    options: {
      enableIvy: false,
    },
  },
};

我如何退出 Angular ngcc？

¥How can I opt-out of Angular ngcc?

如果你在安装 ngcc 后，你可以禁用它：

¥In case you postinstall ngcc, you can disable it:

export default {
  stories: [
    /* ... */
  ],
  addons: [
    /* ... */
  ],
  framework: {
    name: '@storybook/angular',
    options: {
      enableNgcc: false,
    },
  },
};

请报告我们 GitHub 问题跟踪器 中与 Ivy 相关的任何问题，因为对 View Engine 的支持将在 Angular 的未来版本中被放弃。

¥Please report any issues related to Ivy in our GitHub Issue Tracker as the support for View Engine will be dropped in a future release of Angular.

如何使用 Create React App 运行覆盖率测试并省略故事？

¥How can I run coverage tests with Create React App and leave out stories?

Create React App 不允许在你的 package.json 中为 Jest 提供选项，但是你可以使用命令行参数运行 jest：

¥Create React App does not allow providing options to Jest in your package.json, however you can run jest with commandline arguments:

npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stories/*"]'

如何设置 Storybook 以与 Next.js 共享 Webpack 配置？

¥How do I setup Storybook to share Webpack configuration with Next.js?

你通常可以重用 Webpack 规则，方法是将它们放在从 next.config.js 和 .storybook/main.js 文件中 require() 编辑的文件中。例如：

¥You can generally reuse Webpack rules by placing them in a file that is require()-ed from both your next.config.js and your .storybook/main.js files. For example:

export default {
  webpackFinal: async (baseConfig) => {
    const nextConfig = require('/path/to/next.config.js');
 
    // merge whatever from nextConfig into the webpack config storybook will use
    return { ...baseConfig, ...nextConfig };
  },
};

如何在特殊环境中修复模块解析？

¥How do I fix module resolution in special environments?

如果你正在使用 Yarn 即插即用 或你的项目是在 Mono 存储库环境中设置的，则在运行 Storybook 时可能会遇到类似这样的模块解析问题：

¥In case you are using Yarn Plug-n-Play or your project is set up within a mono repository environment, you might run into issues with module resolution similar to this when running Storybook:

WARN   Failed to load preset: "@storybook/react-webpack5/preset"
Required package: @storybook/react-webpack5 (via "@storybook/react-webpack5/preset")

要解决此问题，你可以将包名称封装在 Storybook 配置文件中（即 .storybook/main.js|ts），如下所示：

¥To fix this, you can wrap the package name inside your Storybook configuration file (i.e., .storybook/main.js|ts) as follows:

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
import path from 'path';
 
const getAbsolutePath = (packageName: string): any =>
  path.dirname(require.resolve(path.join(packageName, 'package.json')));
 
const config: StorybookConfig = {
  framework: {
    // Replace your-framework with the same one you've imported above.
    name: getAbsolutePath('@storybook/your-framework'),
    options: {},
  },
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    //👇 Use getAbsolutePath when referencing Storybook's addons and frameworks
    getAbsolutePath('@storybook/addon-essentials'),
  ],
};
 
export default config;

如何使用 Storybook 设置新的 React Context Root API？

¥How do I setup the new React Context Root API with Storybook?

如果你安装的 React 版本等于或高于 18.0.0，则会自动使用新的 React Root API，并且可以使用最新的 React 并发功能。

¥If your installed React Version equals or is higher than 18.0.0, the new React Root API is automatically used and the newest React concurrent features can be used.

你可以通过在 .storybook/main.js 文件中设置以下属性来选择退出新的 React Root API：

¥You can opt-out from the new React Root API by setting the following property in your .storybook/main.js file:

export default {
  framework: {
    name: '@storybook/react-webpack5',
    options: {
      legacyRootApi: true,
    },
  },
};

为什么没有插件通道？

¥Why is there no addons channel?

一个常见的错误是插件尝试访问 "channel"，但未设置通道。它可能发生在几种不同的情况下：

¥A common error is that an addon tries to access the "channel", but the channel is not set. It can happen in a few different cases:

1. 你正在尝试在非浏览器环境（如 Jest）中访问插件通道（例如，通过调用 setOptions）。你可能需要添加一个通道模拟：

   ¥You're trying to access addon channel (e.g., by calling setOptions) in a non-browser environment like Jest. You may need to add a channel mock:

   import { addons, mockChannel } from '@storybook/preview-api';
 
   addons.setChannel(mockChannel());

1. 在 React Native 中，这是 #1192 中记录的特殊情况

   ¥In React Native, it's a special case documented in #1192

为什么控件在画布面板中不可见但在文档中可见？

¥Why aren't Controls visible in the Canvas panel but visible in Docs?

如果你手动添加 Storybook 的依赖，请确保在你的项目中包含 @storybook/addon-controls 依赖并在 .storybook/main.js 中引用它，如下所示：

¥If you're adding Storybook's dependencies manually, make sure you include the @storybook/addon-controls dependency in your project and reference it in your .storybook/main.js as follows:

// .storybook/main.js
 
export default {
  addons: ['@storybook/addon-controls'],
};

为什么插件在组合 Storybook 中不起作用？

¥Why aren't the addons working in a composed Storybook?

Composition 是我们在 6.0 版中发布的一项新功能，但仍存在一些限制。

¥Composition is a new feature that we released with version 6.0, and there are still some limitations to it.

目前，你在组合 Storybook 中使用的插件将不起作用。

¥For now, the addons you're using in a composed Storybook will not work.

我们正在努力克服这个限制，很快你就可以像使用非组合 Storybook 一样使用它们。

¥We're working on overcoming this limitation, and soon you'll be able to use them as if you are working with a non-composed Storybook.

我可以拥有没有本地故事的 Storybook 吗？

¥Can I have a Storybook with no local stories?

除非你的项目中定义了至少一个本地故事（或文档页面），否则 Storybook 不起作用。在这种情况下，本地表示在项目的 .storybook/main.js 配置中引用的 .stories.* 或 .mdx 文件。

¥Storybook does not work unless you have at least one local story (or docs page) defined in your project. In this context, local means a .stories.* or .mdx file that is referenced in your project's .storybook/main.js config.

如果你处于 Storybook 组合 场景中，你有多个 Storybook，并且想要一个没有自己的故事的额外 Storybook，作为项目中所有其他 Storybook 的 "glue"，用于演示/文档目的，你可以执行以下步骤：

¥If you're in a Storybook composition scenario, where you have multiple Storybooks, and want to have an extra Storybook with no stories of its own, that serves as a "glue" for all the other Storybooks in a project for demo/documentation purposes, you can do the following steps:

引入一个单独的 .mdx 文档页面（addon-essentials 或 addon-docs 是必需的），作为介绍页面，如下所示：

¥Introduce a single .mdx docs page (addon-essentials or addon-docs required), that serves as an Introduction page, like so:

{/* Introduction.mdx */}
 
# Welcome
 
Some description here

然后在你的 Storybook 配置文件中引用它：

¥And then refer to it in your Storybook config file:

// .storybook/main.js
const config = {
  // define at least one local story/page here
  stories: ['../Introduction.mdx'],
  // define composed Storybooks here
  refs: {
    firstProject: { title: 'First', url: 'some-url' },
    secondProject: { title: 'Second', url: 'other-url' },
  },
  // ...
};
export default config;

哪些社区插件与最新版本的 Storybook 兼容？

¥Which community addons are compatible with the latest version of Storybook?

从 Storybook 6.0 版开始，我们引入了一些旨在简化开发工作流程的出色功能。

¥Starting with Storybook version 6.0, we've introduced some great features aimed at streamlining your development workflow.

在此，我们想指出，如果你计划使用我们出色的社区创建的插件，你需要考虑到其中一些插件可能正在与过时的 Storybook 版本一起使用。

¥With this, we would like to point out that if you plan on using addons created by our fantastic community, you need to consider that some of those addons might be working with an outdated version of Storybook.

我们希望你能多加注意，以免遇到意外问题。请在下面的 GitHub 问题 中留下评论让我们知道，以便我们收集信息并扩展当前需要更新以与最新版本的 Storybook 配合使用的插件列表。

¥We're actively working to provide a better way to address this situation, but in the meantime, we'd like to ask for a bit of caution on your end so that you don't run into unexpected problems. Let us know by leaving a comment in the following GitHub issue so that we can gather information and expand the current list of addons that need to be updated to work with the latest version of Storybook.

是否可以浏览 Storybook 以前版本的文档？

¥Is it possible to browse the documentation for past versions of Storybook?

随着 6.0 版本的发布，我们也更新了我们的文档。这并不意味着旧文档已被删除。我们保留它是为了帮助你完成 Storybook 迁移过程。将下表中的内容与我们的 迁移指南 结合使用。

¥With the release of version 6.0, we updated our documentation as well. That doesn't mean that the old documentation was removed. We kept it to help you with your Storybook migration process. Use the content from the table below in conjunction with our migration guide.

我们只涵盖版本 5.3 和 5.0，因为它们是 Storybook 的重要里程碑。如果你想再往前追溯一点，则必须在 monorepo 中查看具体版本。

¥We're only covering versions 5.3 and 5.0 as they were important milestones for Storybook. If you want to go back in time a little more, you'll have to check the specific release in the monorepo.

我的工具栏或插件有哪些图标可用？

¥What icons are available for my toolbar or my addon?

使用 @storybook/components 包，你将获得一组图标，可用于自定义 UI。在编写插件或定义 Storybook 全局类型时，请使用下表作为参考。查看此 story 以查看图标的外观。

¥With the @storybook/components package, you get a set of icons that you can use to customize your UI. Use the table below as a reference while writing your addon or defining your Storybook global types. Go through this story to see how the icons look.

我看到 Storybook 生产版本出现 "无预览" 错误

¥I see a "No Preview" error with a Storybook production build

如果你使用 serve 包来验证 Storybook 的生产版本，你将收到该错误。它与 serve 如何处理重写有关。例如，/iframe.html 被重写为 /iframe，你会收到该错误。

¥If you're using the serve package to verify your production build of Storybook, you'll get that error. It relates to how serve handles rewrites. For instance, /iframe.html is rewritten into /iframe, and you'll get that error.

我们建议你改用 http-server 并使用以下命令预览 Storybook：

¥We recommend that you use http-server instead and use the following command to preview Storybook:

npx http-server storybook-static

我可以将 Storybook 与 Vue 2 一起使用吗？

¥Can I use Storybook with Vue 2?

Vue 2 于 2023 年 12 月 31 日进入 生命终结（EOL），Vue 团队不再提供支持。因此，我们已停止在 Storybook 8 及更高版本中支持 Vue 2，并且不会发布任何支持它的新版本。我们建议将你的项目升级到 Vue 3，Storybook 完全支持该功能。如果那不是一个选项，你仍然可以通过使用以下命令安装最新版本的 Storybook 7 将 Storybook 与 Vue 2 一起使用：

¥Vue 2 entered End of Life (EOL) on December 31, 2023, and is no longer supported by the Vue team. As a result, we've stopped supporting Vue 2 in Storybook 8 and above and will not be releasing any new versions that support it. We recommend upgrading your project to Vue 3, which Storybook fully supports. If that's not an option, you can still use Storybook with Vue 2 by installing the latest version of Storybook 7 with the following command:

npx storybook@^7 init

为什么我的代码块没有使用 Storybook MDX 高亮？

¥Why aren't my code blocks highlighted with Storybook MDX?

开箱即用，Storybook 为你可以在代码块中使用的一组语言（例如 Javascript、Markdown、CSS、HTML、Typescript、GraphQL）提供了语法高亮。目前，当你尝试注册自定义语言以获取语法高亮时，存在已知的限制。我们正在努力解决这个问题，一旦可用就会更新此部分。

¥Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) you can use with your code blocks. Currently, there's a known limitation when you try to register a custom language to get syntax highlighting. We're working on a fix for this and will update this section once it's available.

为什么我的 MDX 样式在 Storybook 中不起作用？

¥Why aren't my MDX styles working in Storybook?

使用 MDX 编写文档可能会很麻烦，尤其是在使用带有代码块的换行符时代码的格式。例如，这将中断：

¥Writing documentation with MDX can be troublesome, especially regarding how your code is formatted when using line breaks with code blocks. For example, this will break:

<style>{`
  .class1 {
    ...
  }
 
  .class2 {
    ...
  }
`}</style>

但是这将起作用：

¥But this will work:

<style>
  {`
    .class1 {
      ...
    }
 
    .class2 {
      ...
    }
  `}
</style>

请参阅以下 issue 以获取更多信息。

¥See the following issue for more information.

为什么我的模拟 GraphQL 查询在使用 Storybook 的 MSW 插件时失败？

¥Why are my mocked GraphQL queries failing with Storybook's MSW addon?

如果你正在使用 Vue 3，则需要安装 @vue/apollo-composable。使用 Svelte，你需要安装 @rollup/plugin-replace 并将 rollup.config 文件更新为以下内容：

¥If you're working with Vue 3, you'll need to install @vue/apollo-composable. With Svelte, you'll need to install @rollup/plugin-replace and update your rollup.config file to the following:

// rollup.config
 
// Boilerplate imports
 
import replace from '@rollup/plugin-replace';
const production = !process.env.ROLLUP_WATCH;
 
// Remainder rollup.config implementation
 
export default {
  input: 'src/main.js',
  output: {
    sourcemap: true,
    format: 'iife',
    name: 'app',
    file: 'public/build/bundle.js',
  },
  plugins: [
    // Other plugins
 
    // Configures the replace plugin to allow GraphQL Queries to work properly
    replace({
      'process.env.NODE_ENV': JSON.stringify('development'),
    }),
  ]
};

对于 Angular，最常见的问题是 mockServiceWorker.js 文件的位置。使用此 example 作为参考点。

¥With Angular, the most common issue is the placement of the mockServiceWorker.js file. Use this example as a point of reference.

我可以将其他 GraphQL 提供程序与 Storybook 的 MSW 插件一起使用吗？

¥Can I use other GraphQL providers with Storybook's MSW addon?

是的，请查看 插件示例 以了解如何集成不同的提供商。

¥Yes, check the addon's examples to learn how to integrate different providers.

我可以使用 Storybook 的 MSW 插件模拟 GraphQL 突变吗？

¥Can I mock GraphQL mutations with Storybook's MSW addon?

不，目前，MSW 插件仅支持 GraphQL 查询。如果你有兴趣包含此功能，请在 MSW 插件存储库 中打开一个问题并与维护者进行跟进。

¥No, currently, the MSW addon only has support for GraphQL queries. If you're interested in including this feature, open an issue in the MSW addon repository and follow up with the maintainer.

我的代码如何检测它是否在 Storybook 中运行？

¥How can my code detect if it is running in Storybook?

你可以通过检查 IS_STORYBOOK 全局变量来执行此操作，该变量在 Storybook 中运行时将等于 true。环境变量 process.env.STORYBOOK 也设置为 true。

¥You can do this by checking for the IS_STORYBOOK global variable, which will equal true when running in Storybook. The environment variable process.env.STORYBOOK is also set to true.

为什么使用某些字符时我的故事无法正确显示？

¥Why are my stories not showing up correctly when using certain characters?

Storybook 允许你在命名故事时使用大多数字符。不过，特定字符（例如 #）在 Storybook 生成故事的内部标识符时可能会导致问题，从而导致冲突并错误地输出正确的故事。我们建议稀疏地使用此类字符。

¥Storybook allows you to use most characters while naming your stories. Still, specific characters (e.g., #) can lead to issues when Storybook generates the internal identifier for the story, leading to collisions and incorrectly outputting the correct story. We recommend using such characters sparsely.

为什么 Storybook 的源加载器使用柯里化函数返回未定义？

¥Why is Storybook's source loader returning undefined with curried functions?

这是 Storybook 的已知问题。如果你有兴趣修复它，请使用 工作复制 打开一个问题，以便在将来的版本中进行分类和修复。

¥This is a known issue with Storybook. If you're interested in getting it fixed, open an issue with a working reproduction so that it can be triaged and fixed in future releases.

为什么我的参数不再显示默认值？

¥Why are my args no longer displaying the default values?

在 6.3 版之前，如果指定或从组件的属性推断（例如，React 的 prop 类型、Angular 输入、Vue props），则将未设置的参数设置为 argTypes.defaultValue。从 6.3 版开始，Storybook 不再推断默认值，而是在未设置时将参数的值定义为 undefined，从而允许框架提供其默认值。

¥Before version 6.3, unset args were set to the argTypes.defaultValue if specified or inferred from the component's properties (e.g., React's prop types, Angular inputs, Vue props). Starting with version 6.3, Storybook no longer infers default values but instead defines the arg's value as undefined when unset, allowing the framework to supply its default value.

如果你使用 argTypes.defaultValue 来修复上述问题，则不再需要，你可以安全地将其从故事中删除。

¥If you are using argTypes.defaultValue to fix the above, you no longer need to, and you can safely remove it from your stories.

此外，假设你正在使用 argTypes.defaultValue 或依赖推断来设置参数的默认值。在这种情况下，你应该在组件级别定义参数的值：

¥Additionally, suppose you were using argTypes.defaultValue or relying on inference to set a default value for an arg. In that case, you should define the arg's value at the component level instead:

// MyComponent.stories.js
 
export default {
  component: MyComponent,
  args: {
    //👇 Defining the arg's value at the component level.
    text: 'Something',
  },
};

对于 Storybook 的文档，你可以通过配置 table.defaultValue 设置来手动配置显示的值：

¥For Storybook's Docs, you can manually configure the displayed value by configuring the table.defaultValue setting:

// MyComponent.stories.js
 
export default {
  component: MyComponent,
  argTypes: {
    //👇 Defining the arg's display value in docs.
    text: {
      table: { defaultValue: { summary: 'SomeType<T>' } },
    },
  },
};

为什么 Storybook 的测试运行器不工作？

¥Why isn't Storybook's test runner working?

Storybook 的测试运行器和最新版本的 Jest（即版本 28）存在问题，导致其无法有效运行。作为一种解决方法，你可以将 Jest 降级到以前的稳定版本（即版本 27），然后你就可以运行它了。请参阅以下 issue 以获取更多信息。

¥There's an issue with Storybook's test runner and the latest version of Jest (i.e., version 28), which prevents it from running effectively. As a workaround, you can downgrade Jest to the previous stable version (i.e., version 27), and you'll be able to run it. See the following issue for more information.

Storybook 如何处理环境变量？

¥How does Storybook handle environment variables?

Storybook 内置了对 环境变量 的支持。默认情况下，环境变量仅在 Node.js 代码中可用，在浏览器中不可用，因为某些变量应该保密（例如 API 密钥），并且不会向访问已发布 Storybook 的任何人公开。

¥Storybook has built-in support for environment variables. By default, environment variables are only available in Node.js code and are not available in the browser as some variables should be kept secret (e.g., API keys) and not exposed to anyone visiting the published Storybook.

要公开变量，你必须在其名称前面加上 STORYBOOK_。因此 STORYBOOK_API_URL 将在浏览器代码中可用，但 API_KEY 不会。此外，你还可以通过在 .storybook/main.js 文件中设置 env 字段来自定义要公开的变量。

¥To expose a variable, you must preface its name with STORYBOOK_. So STORYBOOK_API_URL will be available in browser code but API_KEY will not. Additionally you can also customize which variables are exposed by setting the env field in the .storybook/main.js file.

变量是在编译 JavaScript 时设置的，因此在启动开发服务器或构建 Storybook 时也是如此。环境变量文件不应提交给 Git，因为它们通常包含不安全添加到 Git 的机密。相反，将 .env.* 添加到你的 .gitignore 文件中，并在你的托管服务提供商（例如 GitHub）上手动设置环境变量。

¥Variables are set when JavaScript is compiled so when the development server is started or you build your Storybook. Environment variable files should not be committed to Git as they often contain secrets which are not safe to add to Git. Instead, add .env.* to your .gitignore file and set up the environment variables manually on your hosting provider (e.g., GitHub).