常见问题

以下是常见问题的解答。如果您有任何疑问，可以在我们的 GitHub 讨论区 提问。

错误：未找到 angular.json 文件

Storybook 可以为单项目和多项目 Angular 工作区进行设置。要为项目设置 Storybook，请在包含 angular.json 文件的工作区的根目录运行 安装命令。在初始化过程中，将创建 .storybook 文件夹，并编辑 angular.json 文件，为选定的项目添加 Storybook 配置。在根目录运行该命令很重要，以确保 Storybook 能正确检测到所有项目。

如何选择退出 Angular Ivy？

如果您在 Angular Ivy 方面遇到问题，可以在您的 main.js|ts 文件中将其禁用

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

如何选择退出 Angular ngcc？

如果您在 postinstall 中运行 ngcc，可以禁用它

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

如果您在使用 Ivy 时遇到问题，请在我们的 GitHub 问题跟踪器 中报告与 Ivy 相关的问题，因为在未来的 Angular 版本中将不再支持 View Engine。

如何使用 Create React App 运行覆盖率测试并排除 stories？

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

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

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

您通常可以通过将 Webpack 规则放在一个文件，然后从您的 next.config.js 和 .storybook/main.js|ts 文件中导入来重用它们。例如

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

如何修复特殊环境下的模块解析问题？

如果您正在使用 Yarn Plug-n-Play 或者您的项目是设置在 mono repository 环境中，在运行 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）中，将包名用以下方式括起来

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
 
const getAbsolutePath = (packageName: string) =>
  dirname(fileURLToPath(import.meta.resolve(`${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-docs'),
  ],
};
 
export default config;

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

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

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

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

为什么没有 addons channel？

一个常见的错误是，插件试图访问 "channel"，但 channel 未设置。这可能在几种情况下发生

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

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

2. 在 React Native 中，这是一个特殊情况，记录在 #1192 中

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

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

目前，您在组合 Storybook 中使用的插件将无法工作。

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

我可以有一个不包含本地 stories 的 Storybook 吗？

Storybook 除非您的项目中至少定义了一个本地 story（或 docs 页面），否则将无法工作。在此上下文中，本地是指 .stories.* 或 .mdx 文件，这些文件在项目的 .storybook/main.js 配置中被引用。

如果您处于 Storybook composition 场景，拥有多个 Storybook，并且想要一个没有自己 stories 的额外 Storybook，该 Storybook 可作为项目中所有其他 Storybook 的“粘合剂”，用于演示/文档目的，您可以执行以下步骤

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

# Welcome
 
Some description here

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

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 兼容？

从 Storybook 版本 6.0 开始，我们引入了一些旨在简化开发流程的强大功能。

因此，我们想指出的是，如果您计划使用我们出色的社区创建的插件，您需要考虑到其中一些插件可能与旧版本的 Storybook 兼容。

我们正在积极努力提供更好的方法来解决这种情况，但在此期间，我们希望您多加注意，以免遇到意外问题。请在以下 GitHub issue 中留下评论，以便我们收集信息并扩展需要更新以与最新版本的 Storybook 兼容的插件列表。

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

随着 6.0 版本的发布，我们也更新了我们的文档。这并不意味着旧文档已被删除。我们保留了它们，以帮助您迁移 Storybook。请将下表中的内容与我们的 迁移指南 一起使用。

我们只涵盖 5.3 和 5.0 版本，因为它们是 Storybook 的重要里程碑。如果您想回顾更早的版本，您需要检查 monorepo 中的特定版本。

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

使用 @storybook/icons 包，您可以获得一组可用于自定义 UI 的图标。请查看 文档 了解图标的外观，并在编写插件或定义 Storybook 全局类型时将其用作参考。

在 Storybook 生产构建中看到“No Preview”错误

如果您使用 serve 包来验证 Storybook 的生产构建，您将遇到该错误。这与 serve 处理重写的方式有关。例如，/iframe.html 被重写为 /iframe，您将看到该错误。

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

npx http-server storybook-static

可以使用 Storybook 和 Vue 2 吗？

Vue 2 已于 2023 年 12 月 31 日进入 生命周期结束 (EOL)，Vue 团队不再支持它。因此，我们已停止支持 Storybook 8 及以上版本中的 Vue 2，也不会发布支持它的新版本。我们建议将您的项目升级到 Vue 3，Storybook 完全支持 Vue 3。如果这不可行，您仍然可以通过安装最新版本的 Storybook 7 来使用 Storybook 和 Vue 2，命令如下

npx storybook@^7 init

为什么我的代码块在 Storybook MDX 中没有高亮显示？

开箱即用，Storybook 为您可以使用代码块的多种语言（例如 Javascript、Markdown、CSS、HTML、Typescript、GraphQL）提供语法高亮。目前，当您尝试注册自定义语言以获得语法高亮时，存在已知限制。我们正在修复此问题，一旦可用，我们将更新此部分。

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

使用 MDX 编写文档可能会很麻烦，尤其是在代码格式化方面，因为在代码块中使用换行符。例如，这会破坏

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

但这会起作用

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

有关更多信息，请参阅以下 issue。

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

如果您使用 Vue 3，您需要安装 @vue/apollo-composable。对于 Svelte，您需要安装 @rollup/plugin-replace 并将您的 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 文件的放置位置。请参考此 示例。

可以使用 Storybook 的 MSW 插件和其他 GraphQL 提供商吗？

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

可以使用 Storybook 的 MSW 插件模拟 GraphQL mutations 吗？

否，目前 MSW 插件仅支持 GraphQL queries。如果您对此功能感兴趣，请在 MSW 插件仓库 中打开一个 issue 并与维护者跟进。

为什么在使用某些特殊字符时，我的 stories 显示不正确？

Storybook 允许您在命名 stories 时使用大多数字符。但是，特定的字符（例如 #）在 Storybook 生成 story 的内部标识符时可能会导致问题，从而导致冲突并错误地输出正确的 story。我们建议谨慎使用这些字符。

为什么 Storybook 的 source loader 在使用 curried functions 时返回 undefined？

这是一个已知的 Storybook 问题。如果您对此有兴趣并希望得到修复，请提供一个 可用的重现示例 来打开一个 issue，以便我们对其进行分类并在未来的版本中修复。

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

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

如果您使用 argTypes.defaultValue 来修复上述问题，则不再需要它，并且可以安全地将其从您的 stories 中删除。

此外，如果您曾使用 argTypes.defaultValue 或依赖推断来为 arg 设置默认值。在这种情况下，您应该在组件级别定义 arg 的值，而不是

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

对于 Storybook 的 Docs，您可以通过配置 table.defaultValue 设置来手动配置显示的值

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

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

Storybook 的测试运行器与最新版本的 Jest（即 28 版本）存在一个问题，这会影响其有效运行。作为一种变通方法，您可以将 Jest 降级到上一个稳定版本（即 27 版本），这样就可以运行它了。有关更多信息，请参阅以下 issue。

Storybook 如何处理环境变量？

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

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

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