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, vue3-vite)
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, vue3-vite)
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, vue3-vite)
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 加载器时，您应该 排除该加载器的 .ejs 文件扩展名。

导入自定义 Webpack 配置

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

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
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 的默认 Webpack 配置为大多数项目设置提供了支持，无需任何额外的配置。但是，根据项目的配置或选择的框架，当从 tsconfig 文件中使用别名时，您可能会遇到 TypeScript 模块在 Storybook 中未解析的问题。如果您遇到此问题，可以使用 tsconfig-paths-webpack-plugin 并在扩展 Storybook 的 Webpack 配置时按如下方式操作

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
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, vue3-vite)
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(__dirname, '../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 构建器