加入直播：周四，美国东部时间上午 11 点，Storybook 9 版本发布和 AMA
86,718
文档
Storybook 文档

Webpack

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

配置

默认情况下，Storybook 为 Webpack 提供零配置支持，并自动设置一个基线配置，以适用于最常见的用例。但是，您可以扩展 Storybook 配置文件（即 .storybook/main.js|ts），并提供额外的选项来提升 Storybook 的性能或根据您的需求进行定制。下面列出了可用选项及其使用示例。

选项描述
lazyCompilation启用 Webpack 的实验性 惰性编译 (lazy compilation)
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 加载器时，应为该加载器 排除 .ejs 文件扩展名。

导入自定义 Webpack 配置

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

.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 配置，对 JavaScript 和 TypeScript 文件使用 swc-loader。此外，它还会检测并使用您项目的 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 配置，对 JavaScript 和 TypeScript 文件使用 babel-loader 作为默认加载器。此外，它还会检测并使用您项目的 Babel 配置。

疑难解答

Storybook 中无法解析 TypeScript 模块

Storybook 的默认 Webpack 配置支持大多数项目设置，无需额外配置。然而，根据您的项目配置或所选框架的不同，当 TypeScript 模块从您的 tsconfig 文件别名时，您可能会遇到 Storybook 中无法解析这些模块的问题。如果您遇到此问题，可以在扩展 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(__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 网站上提供的说明来更新您的配置。

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

此页面有用吗？
✍️ 在 Github 上编辑