常見問題

以下是一些常見問題的解答。如果您有問題，可以在我們的 GitHub 討論區 提出。

錯誤：找不到 angular.json 檔案

Storybook 可以為單一專案和多專案 Angular 工作區進行設定。若要為專案設定 Storybook，請在 安裝指令 所在的 angular.json 檔案的根目錄執行。在初始化期間，將會建立 .storybook 資料夾，並編輯 angular.json 檔案，為選取的專案新增 Storybook 設定。務必在根目錄層級執行指令，以確保 Storybook 正確偵測所有專案。

如何選擇退出 Angular Ivy？

如果您在使用 Angular Ivy 時遇到問題，可以在 main.js|ts 中停用它

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,
    },
  },
};

由於 Angular 未來的版本將會捨棄對 View Engine 的支援，請在我們的 GitHub Issue Tracker 中回報任何與 Ivy 相關的問題。

如何使用 Create React App 執行覆蓋率測試並排除 stories？

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|ts 檔案中 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 Context Root API？

如果您的 React 版本等於或高於 18.0.0，則會自動使用新的 React Root API，並且可以使用最新的 React 並行功能。

您可以透過在 .storybook/main.js|ts 檔案中設定以下屬性來選擇退出新的 React Root API

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

為什麼沒有 addons channel？

常見的錯誤是擴充套件嘗試存取「channel」，但未設定 channel。這可能在幾種不同的情況下發生

1. 您嘗試在非瀏覽器環境（例如 Jest）中存取擴充套件 channel（例如，透過呼叫 setOptions）。您可能需要新增 channel 模擬

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

2. 在 React Native 中，這是一個特殊情況，記錄在 #1192 中

為什麼控制項在 Canvas 面板中不可見，但在文件 (Docs) 中可見？

如果您手動新增 Storybook 的依賴項，請確保在您的專案中包含 @storybook/addon-controls 依賴項，並在您的 .storybook/main.js|ts 中參考它，如下所示

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

為什麼擴充套件在組合式 Storybook 中無法運作？

組合是我們在 6.0 版本中發布的新功能，它仍然存在一些限制。

目前，您在組合式 Storybook 中使用的擴充套件將無法運作。

我們正在努力克服此限制，很快您就能像使用非組合式 Storybook 一樣使用它們。

我可以建立一個沒有本地 stories 的 Storybook 嗎？

除非您的專案中至少定義一個本地 story（或文件頁面），否則 Storybook 無法運作。在此上下文中，本地表示在專案的 .storybook/main.js 設定中參考的 .stories.* 或 .mdx 檔案。

如果您處於 Storybook 組合 情境中，其中有多個 Storybook，並且想要有一個額外的 Storybook，它本身沒有 stories，而是作為專案中所有其他 Storybook 的「黏合劑」，用於演示/文件目的，您可以執行以下步驟

引入一個單一的 .mdx 文件頁面（需要 addon-essentials 或 addon-docs），作為簡介頁面，如下所示

# Welcome
 
Some description here

然後在您的 Storybook 設定檔中參考它

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 issue 中留言告訴我們，以便我們可以收集資訊並擴展目前需要更新以適用於最新版本的 Storybook 的擴充套件清單。

是否可以瀏覽舊版 Storybook 的文件？

隨著 6.0 版的發布，我們也更新了文件。這並不意味著舊文件已被移除。我們保留了它，以協助您進行 Storybook 遷移過程。將下表中的內容與我們的 遷移指南 結合使用。

我們僅涵蓋 5.3 和 5.0 版本，因為它們是 Storybook 的重要里程碑。如果您想再回到過去一點，則必須查看 monorepo 中的特定版本。

我的工具列或擴充套件可以使用哪些圖示？

透過 @storybook/components 套件，您可以獲得一組圖示，可用於自訂 UI。在撰寫擴充套件或定義 Storybook 全域類型時，請使用下表作為參考。瀏覽此 story 以查看圖示的外觀。

我在 Storybook 生產版本中看到「No Preview」錯誤

如果您使用 serve 套件來驗證 Storybook 的生產版本，您會收到該錯誤。這與 serve 處理重寫的方式有關。例如，/iframe.html 會被重寫為 /iframe，您會收到該錯誤。

我們建議您改用 http-server，並使用以下指令預覽 Storybook

npx http-server storybook-static

我可以將 Storybook 與 Vue 2 一起使用嗎？

Vue 2 已於 2023 年 12 月 31 日進入 生命週期結束 (EOL)，且不再受 Vue 團隊支援。因此，我們已停止在 Storybook 8 及更高版本中支援 Vue 2，並且不會發布任何支援它的新版本。我們建議將您的專案升級到 Storybook 完全支援的 Vue 3。如果這不是一個選項，您仍然可以使用 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>

請參閱以下 issue 以取得更多資訊。

為什麼我模擬的 GraphQL 查詢在使用 Storybook 的 MSW 擴充套件時失敗？

如果您使用 Vue 3，則需要安裝 @vue/apollo-composable。對於 Svelte，您需要安裝 @rollup/plugin-replace 並將您的 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 檔案的放置位置。請使用此 範例 作為參考點。

我可以將其他 GraphQL 提供者與 Storybook 的 MSW 擴充套件一起使用嗎？

可以，查看擴充套件的範例，以了解如何整合不同的提供者。

我可以使用 Storybook 的 MSW 擴充套件模擬 GraphQL mutations 嗎？

目前不行，MSW 擴充套件目前僅支援 GraphQL 查詢。如果您有興趣加入此功能，請在 MSW 擴充套件儲存庫 中開啟 issue，並與維護者聯繫。

為什麼我的 stories 在使用某些字元時無法正確顯示？

Storybook 允許您在命名 stories 時使用大多數字元。但是，特定字元（例如 #）可能會導致 Storybook 為 story 產生內部識別碼時出現問題，進而導致衝突並錯誤地輸出正確的 story。我們建議謹慎使用此類字元。

為什麼 Storybook 的 source loader 在使用柯里化函數時會回傳 undefined？

這是 Storybook 已知的問題。如果您有興趣協助修復此問題，請開啟一個 issue 並提供可重現問題的範例，以便我們分類並在未來版本中修復。

為什麼我的 args 不再顯示預設值？

在 6.3 版本之前，未設定的 args 會被設定為 argTypes.defaultValue (如果已指定) 或從元件的屬性 (例如，React 的 prop types、Angular 的 inputs、Vue 的 props) 推斷而來。從 6.3 版本開始，Storybook 不再推斷預設值，而是將未設定的 arg 值定義為 undefined，以允許框架提供其預設值。

如果您之前使用 argTypes.defaultValue 來解決上述問題，現在已不再需要，您可以安全地從您的 stories 中移除它。

此外，假設您之前使用 argTypes.defaultValue 或依賴推斷來設定 arg 的預設值。在這種情況下，您應該改為在元件層級定義 arg 的值

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

對於 Storybook 的 Docs，您可以透過設定 table.defaultValue 設定來手動配置顯示的值。

export default {
  component: MyComponent,
  argTypes: {
    //👇 Defining the arg's display value in docs.
    text: {
      table: { defaultValue: { summary: 'SomeType<T>' } },
    },
  },
};

為什麼 Storybook 的 test runner 無法運作？

Storybook 的 test runner 和最新版本的 Jest (即 28 版) 存在一個問題，導致它無法有效運行。作為一種臨時解決方案，您可以將 Jest 降級到先前的穩定版本 (即 27 版)，就可以運行它。請參閱以下 issue 以獲取更多資訊。

Storybook 如何處理環境變數？

Storybook 內建支援環境變數。預設情況下，環境變數僅在 Node.js 程式碼中可用，在瀏覽器中不可用，因為某些變數應保持機密 (例如，API 金鑰)，且不應暴露給任何訪問已發佈 Storybook 的人。

若要公開變數，您必須在其名稱前加上 STORYBOOK_。因此，STORYBOOK_API_URL 將在瀏覽器程式碼中可用，但 API_KEY 將不可用。此外，您還可以透過在 env 檔案中設定 .storybook/main.js 欄位來自訂要公開哪些變數。

變數在編譯 JavaScript 時設定，也就是當開發伺服器啟動或您建置 Storybook 時。環境變數檔案不應提交到 Git，因為它們通常包含不適合添加到 Git 的機密資訊。相反地，將 .env.* 新增到您的 .gitignore 檔案中，並在您的託管供應商 (例如，GitHub) 上手動設定環境變數。