常见问题解答

以下是一些常见问题的解答。如果您有问题，可以在我们的 GitHub discussions 中提问。

错误：未找到 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,
    },
  },
};

请在我们的 GitHub Issue Tracker 中报告任何与 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 与 Next.js 共享 Webpack 配置？

通常可以通过将 Webpack 规则放在一个文件中来实现复用，该文件在您的 next.config.js 和您的 .storybook/main.js|ts 文件中都被 require() 引用。例如

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 };
  },
};

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

如果您正在使用 Yarn Plug-n-Play 或您的项目设置在单仓库环境中，在运行 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 path from 'path';
 
const _require = typeof require === 'undefined' ? import.meta : require;
const getAbsolutePath = (packageName: string): any =>
  path.dirname(_require.resolve(path.join(packageName, 'package.json'))).replace(/^file:\/\//, '');
 
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;

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

如果您安装的 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）中尝试访问 addon channel（例如，通过调用 setOptions）。您可能需要添加 channel mock

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

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

为什么插件在组合 Storybook 中无法工作？

组合是我们随 6.0 版本发布的新功能，目前仍有一些限制。

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

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

我可以创建一个没有本地故事 (stories) 的 Storybook 吗？

Storybook 只有在您的项目中定义了至少一个本地故事 (story)（或文档页面）时才能工作。在此上下文中，本地指的是您的项目 .storybook/main.js 配置中引用的 .stories.* 或 .mdx 文件。

如果您处于 Storybook 组合 场景中，您有多个 Storybook，并希望有一个额外的 Storybook 没有自己的故事 (stories)，仅作为项目中所有其他 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 生产构建时出现“无预览”错误

如果您使用 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，并且不会发布支持它的新版本。我们建议将您的项目升级到 Storybook 完全支持的 Vue 3。如果这不是一个选项，您仍然可以通过安装最新版本的 Storybook 7 来使用 Storybook 和 Vue 2，命令如下

npx storybook@^7 init

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

Storybook 开箱即用地为一组语言（例如 Javascript, Markdown, CSS, HTML, Typescript, GraphQL）提供语法高亮显示，您可以在代码块中使用。目前，当您尝试注册自定义语言以获取语法高亮时，存在一个已知限制。我们正在为此努力修复，修复可用后将更新此部分。

为什么我的 Storybook MDX 样式不生效？

使用 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 文件的位置。请参考此示例。

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

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

我可以使用 Storybook 的 MSW 插件模拟 GraphQL 变更（mutation）吗？

目前不行，MSW 插件目前只支持 GraphQL 查询。如果你有兴趣包含此功能，请在MSW 插件仓库中提出 issue 并与维护者联系。

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

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

为什么 Storybook 的源代码加载器对柯里化（curried）函数返回 undefined？

这是 Storybook 的一个已知问题。如果你有兴趣解决此问题，请提供一个可重现的示例来开启一个 issue，以便在未来的版本中进行分类和修复。

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

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

如果你之前使用 argTypes.defaultValue 来解决上述问题，现在不再需要这样做，你可以安全地将其从故事中移除。

此外，如果你之前使用 argTypes.defaultValue 或依赖推断来为 arg 设置默认值，那么你应该改为在组件级别定义 arg 的值。

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

对于 Storybook 的文档，你可以通过配置 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），这样就可以运行了。更多信息请参阅以下问题。

Storybook 如何处理环境变量？

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

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

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