84,593
文件
Storybook 文件

Webpack

Storybook Webpack 建構器是 Storybook 的預設建構器。此建構器可讓您為元件建立無縫的開發和測試體驗，並提供有效率的方式來獨立開發 UI 元件，讓您能夠利用現有的 Webpack 設定與 Storybook 搭配使用。

設定

依預設，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, 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 載入器時，您應該為該載入器 exclude .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 設定。

疑難排解

TypeScript 模組未在 Storybook 中解析

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 網站上提供的指示來更新您的設定。

深入了解建置器

此頁面是否實用？
✍️ 在 Github 上編輯