常见问题

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

错误: 未找到 angular.json 文件

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

如何禁用 Angular Ivy？

如果您在使用 Angular Ivy 时遇到问题，可以在 main.js 文件中将其禁用。

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 运行覆盖率测试并排除故事？

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 文件中都 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 上下文根 API？

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

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

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

为什么没有插件频道？

一个常见的错误是插件试图访问“频道”，但频道没有设置。这可能会在以下几种情况下发生。

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

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

2. 在 React Native 中，这是一个特殊情况，在 #1192 中有说明。

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

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

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

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

组合式 Storybook 是我们在 6.0 版本中发布的一项新功能，它仍然有一些限制。

目前，你在组合式 Storybook 中使用的插件将无法正常工作。

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

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

除非你的项目中至少定义了一个本地故事（或文档页面），否则 Storybook 无法正常工作。在这种情况下，本地指的是 .stories.* 或 .mdx 文件，它们在项目的 .storybook/main.js 配置中被引用。

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

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

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

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

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

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

因此，我们想指出，如果你打算使用我们优秀的社区创建的插件，你需要考虑其中一些插件可能与过时的 Storybook 版本一起工作。

我们正在积极努力提供更好的方法来解决这种情况，但在目前，我们想让你谨慎一些，这样你才能避免遇到意外问题。请在以下 GitHub 问题 中留下评论，以便我们收集信息并扩展当前需要更新才能与最新版本 Storybook 一起工作的插件列表。

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

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

我们只涵盖 5.3 和 5.0 版本，因为它们是 Storybook 的重要里程碑。如果你想进一步回溯时间，你需要检查单仓库中的特定版本。

我的工具栏或附加组件可以使用哪些图标？

使用 @storybook/components 包，您可以获得一组图标，可以使用它们来自定义您的 UI。在编写附加组件或定义 Storybook 全局类型时，请将下表作为参考。通过这个 故事 来了解图标的外观。

我在 Storybook 生产版本中看到“无预览”错误

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

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

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

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

// 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 变异吗？

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

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

您可以通过检查 IS_STORYBOOK 全局变量来做到这一点，它在 Storybook 中运行时将等于 true。环境变量 process.env.STORYBOOK 也设置为 true。

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

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

为什么 Storybook 的源加载器在使用柯里化函数时返回 undefined？

这是一个 Storybook 已知问题。如果您有兴趣解决它，请使用 可复现的示例 提交一个 issue，以便在未来的版本中进行分类和修复。

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

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

如果您正在使用 argTypes.defaultValue 来解决上述问题，那么您不再需要这样做，可以安全地从您的故事中删除它。

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

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

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

// MyComponent.stories.js
 
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 将不可用。此外，您还可以通过设置 env 字段（在 .storybook/main.js 文件中）来自定义哪些变量会被公开。

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