88,244
文档
Storybook Docs

Webpack

Storybook 的 Webpack 构建器是 Storybook 的默认构建器。此构建器可为您提供无缝的组件开发和测试体验，并提供一种独立开发 UI 组件的高效方式，使您可以利用现有的 Webpack 配置与 Storybook 一起使用。

配置

默认情况下，Storybook 提供零配置的 Webpack 支持，并自动设置一个基础配置，该配置旨在满足最常见的用例。但是，您可以扩展 Storybook 的配置文件（例如 .storybook/main.js|ts）并提供其他选项来提高 Storybook 的性能或根据您的需求进行自定义。下面列出了可用选项以及如何使用它们的示例。

选项描述
lazyCompilation启用 Webpack 实验性的 延迟编译
core: { builder: { options: { lazyCompilation: true } } }
fsCache配置 Webpack 的文件系统 缓存 功能
core: { builder: { options: { fsCache: true } } }
.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-webpack5',
      options: {
        fsCache: true,
        lazyCompilation: true,
      },
    },
  },
};
 
export default config;

覆盖默认配置

Storybook 的 Webpack 配置基于 Webpack 5，这使得它可以进行扩展以适应项目的需求。如果您需要添加加载器或插件，可以在 .storybook/main.js|ts 文件中提供 webpackFinal 配置项。该配置项应导出一个函数，该函数接收基础配置作为第一个参数，并接收 Storybook 的选项对象作为第二个参数。例如

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
};
 
export default config;

当 Storybook 启动时，它会自动将配置合并到自身中。但是，当提供 webpackFinal 配置项时，您将负责自行合并配置。我们建议您负责任地处理对 config 对象的更改，同时保留 entry 和 output 属性。

使用 Webpack 插件

自定义 Storybook 配置的另一种方法是添加自定义插件或加载器，以帮助进行代码优化、资产管理或其他任务。尽管如此，由于 Storybook 依赖于 HtmlWebpackPlugin 来生成预览页面，我们建议您将更改附加到 config.plugins 数组，而不是覆盖它。例如

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    config.plugins.push(/* ... */);
    return config;
  },
};
 
export default config;

此外，在使用不明确包含特定文件扩展名（例如，通过 test 属性）的 Webpack 加载器时，您应该为该加载器 exclude .ejs 文件扩展名。

导入自定义 Webpack 配置

如果您已经有一个现有的 Webpack 配置文件需要与 Storybook 重用，您可以导入它并将其合并到默认配置中。例如

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
import custom from '../webpack.config.js'; // 👈 Custom Webpack configuration being imported.
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    return {
      ...config,
      module: { ...config.module, rules: [...config.module.rules, ...custom.module.rules] },
    };
  },
};
 
export default config;

基于生成器脚手架的项目可能需要您导入其特定的 Webpack 配置文件。我们建议您阅读生成器的文档以获取更多信息。

调试 Webpack 配置

如果您打算调试 Storybook 使用的 Webpack 配置，您可以使用 Storybook CLI 来帮助您。如果您正在 开发模式下运行，您可以使用以下命令

npm run storybook -- --debug-webpack

此外，如果您正在生成 Storybook 的 静态构建，您可以使用以下命令

npm run build-storybook -- --debug-webpack

编译器支持

Storybook 采取一种与编译器无关的打包方法。这允许您使用自己的应用程序打包器（例如 Babel、SWC），并确保与庞大的 Webpack 5 项目生态系统兼容。

SWC

如果您的项目是使用 SWC 构建的，请使用 @storybook/addon-webpack5-compiler-swc 插件。此插件提高了与 Webpack 5 项目的生态系统兼容性，同时保持了高性能。运行以下命令以自动设置该插件

npx storybook@latest add @storybook/addon-webpack5-compiler-swc

可以提供其他选项来定制 SWC 配置。有关更多信息，请参阅 SWC API 文档。

启用此插件后，它将调整 Webpack 配置以使用 swc-loader 处理 JavaScript 和 TypeScript 文件。此外，它还将检测并使用您项目的 SWC 配置。

Babel

如果您正在使用 Babel 工具来为特定功能（包括 TypeScript 或其他现代 JavaScript 功能）提供支持的项目，您可以使用 @storybook/addon-webpack5-compiler-babel 插件，以便将其包含在您的 Storybook 中，从而确保与您的项目兼容。运行以下命令以自动设置该插件

npx storybook@latest add @storybook/addon-webpack5-compiler-babel

可以提供其他选项来定制 Babel 配置。有关更多信息，请参阅 babel API 文档，或者如果您正在开发插件，请参阅 babelDefault 文档。

启用后，该插件将调整 Webpack 配置，使用 babel-loader 作为 JavaScript 和 TypeScript 文件的默认加载器。此外，它将检测并使用您项目的 Babel 配置。

故障排除

Storybook 中未解析 TypeScript 模块

Storybook 的默认 Webpack 配置支持大多数项目设置，无需任何额外配置。尽管如此，根据您的项目配置或选择的框架，您可能会遇到 TypeScript 模块在 Storybook 中未被解析的问题，当它们从您的 tsconfig 文件进行别名时。如果您遇到此问题，可以在 扩展 Storybook 的 Webpack 配置时使用 tsconfig-paths-webpack-plugin，如下所示

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.plugins = [
        ...(config.resolve.plugins || []),
        new TsconfigPathsPlugin({
          extensions: config.resolve.extensions,
        }),
      ];
    }
    return config;
  },
};
 
export default config;

但是，如果您正在使用一个提供默认别名配置的框架（例如 Next.js、Nuxt），并且您想将 Storybook 配置为使用相同的别名，您可能不需要安装任何额外的包。相反，您可以扩展 Storybook 的默认配置以使用框架提供的相同别名。例如，要为 @ 导入路径设置别名，您可以将以下内容添加到您的 .storybook/main.js|ts 文件中

.storybook/main.ts
import path from 'path';
// Replace your-framework with the framework you are using, e.g. react-webpack5, nextjs, angular, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@': path.resolve(process.cwd(), 'src'),
      };
    }
    return config;
  },
};
 
export default config;

预打包的资产未显示在 Storybook UI 中

由于 Storybook 依赖于 esbuild 来构建其内部管理器，因此对使用 managerWebpack 打包资产的支持将不再影响 Storybook UI。我们建议从您的 Storybook 配置文件中删除现有的 managerWebpack 配置项，并提前将除图像或 CSS 以外的资产打包到 JavaScript 中。

Storybook 不支持 Webpack 4

已删除对 Webpack 4 的支持，并且不再维护。如果您正在升级您的 Storybook，它将自动使用 Webpack 5 并尝试迁移您的配置。但是，如果您使用自定义 Webpack 配置，您可能需要更新它以使其与 Webpack 5 兼容。迁移过程对于确保您的项目在新版本的 Storybook 中顺利运行至关重要。您可以按照 Webpack 网站上提供的说明来更新您的配置。

了解有关构建器的更多信息

  • Vite 构建器 用于使用 Vite 进行打包
  • Webpack 构建器用于使用 Webpack 进行打包
  • 构建器 API 用于构建 Storybook 构建器
此页面有用吗？
✍️ 在 GitHub 上编辑