常见问题

以下是一些常见问题的解答。如果您有疑问，可以在我们的 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,
    },
  },
};

请在我们的 GitHub Issue Tracker 中报告任何与 Ivy 相关的问题，因为对 View Engine 的支持将在 Angular 的未来版本中删除。

如何使用 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-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？

如果您安装的 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 通道？

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

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

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

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

为什么 Controls 在 Canvas 面板中不可见，但在 Docs 中可见？

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

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

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

组合是我们随版本 6.0 发布的新功能，它仍然存在一些限制。

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

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

我可以拥有一个没有本地 stories 的 Storybook 吗？

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

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

引入一个单独的 .mdx 文档页面（需要 addon-essentials 或 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/components 包，您可以获得一组图标，您可以使用这些图标自定义您的 UI。在编写插件或定义 Storybook 全局类型时，请使用下表作为参考。浏览此 story 以查看图标的外观。

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

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

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

npx http-server storybook-static

我可以在 Vue 2 中使用 Storybook 吗？

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

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

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

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

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

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

为什么在使用某些字符时我的 stories 未正确显示？

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

为什么 Storybook 的 source loader 在使用柯里化函数时返回 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 来修复上述问题，您不再需要这样做，并且可以安全地从您的 stories 中删除它。

此外，假设您之前使用 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 版本），这样您就可以运行它了。有关更多信息，请参阅以下 issue。

Storybook 如何处理环境变量？

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

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

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