Storybook 完全指南

由 FeiYueh 親自審稿驗證 · 最後更新於 2026-05-19

Storybook 是目前前端開發生態中採用率最高的 UI 元件開發工具， 每週 npm 下載量超過 1,000 萬次（npm 統計，2025 Q4） ，被 Airbnb、GitHub、Shopify 等公司列為標準前端工具鏈的一部分。它讓你在完全隔離的環境中開發、預覽、測試每一個 UI 元件，不需要啟動完整應用，讓設

Storybook 是目前前端開發生態中採用率最高的 UI 元件開發工具， 每週 npm 下載量超過 1,000 萬次（npm 統計，2025 Q4） ，被 Airbnb、GitHub、Shopify 等公司列為標準前端工具鏈的一部分。它讓你在完全隔離的環境中開發、預覽、測試每一個 UI 元件，不需要啟動完整應用，讓設計與開發的協作成本降低 40% 以上。 Storybook 解決什麼問題 傳統 UI 開發最大的瓶頸是「狀態重現困難」——要看一個 Button 在 disabled 狀態下的樣子，開發者必須先登入、導航、觸發特定條件，才能看到那個邊緣狀態。Storybook 把這個流程翻轉：每一個狀態都成為一個獨立的「Story」，可以直接在瀏覽器中點擊預覽，無需任何前置操作。 元件的隔離開發帶來另一個隱性效益：可測試性大幅提升。當元件不依賴全域 store 或路由就能渲染，寫單元測試的阻力幾乎消失。 Storybook 在 GitHub 上累計超過 84,000 顆星（2025 年） ，是前端工具類中星數最高的非框架專案之一。 Storybook v8 的核心功能 2024 年 3 月發布的 Storybook 8 帶來了三項關鍵升級，其中影響最大的是 Vitest 整合 ：Story 可以直接作為 Vitest 的測試用例執行，不再需要為元件測試維護兩套設定檔。 Component Story Format 3（CSF3） CSF3 是 Storybook 的標準 Story 格式，讓每一個 Story 只需要 3-5 行程式碼。以 React 為例，一個完整的 Button Story 長這樣： export const Primary = { args: { label: '送出', variant: 'primary', disabled: false, }, }; args 物件會自動對應到 Controls 面板，讓任何人都能在瀏覽器中即時調整參數，不需要改程式碼。這個設計使設計師與 PM 可以直接操作元件，而不是看截圖。 Autodocs 自動生成文件 Storybook 8 的 Autodocs 功能可以從 TypeScript 的 Props 型別定義，自動產生互動式 API 文件頁面。在 Story 檔案的 default export 加上 tags: ['autodocs'] ，Storybook 就會自動建立一份包含所有 Props 說明、預設值、可接受值的文件頁，省去手動維護文件的時間。 Visual Testing 視覺測試 透過 Chromatic（Storybook 官方出品的視覺測試服務） ，每次 commit 都會對比 Story 的渲染截圖，自動標記視覺差異。這讓 CSS 回歸錯誤在 PR review 階段就被攔截，而不是在 QA 或上線後才發現。 安裝與初始化 Storybook 8 支援 React、Vue 3、Angular、Svelte、Web Components，初始化指令統一為： npx storybook@latest init 這個指令會自動偵測你的專案框架（透過讀取 package.json 的 dependencies），安裝對應的 preset，並產生 .storybook/main.ts 設定檔與範例 Story 檔案。整個流程在乾淨的 Vite + React 專案上約需 45 秒。 執行完畢後， npm run storybook 會在 localhost:6006 啟動開發伺服器。所有符合 *.stories.tsx （或 .jsx 、 .ts ）命名規則的檔案都會自動被掃描並顯示在左側導覽樹。 目錄結構建議 Story 檔案放在元件旁邊（colocated）比集中放在 stories/ 資料夾更容易維護。結構建議如下： src/ components/ Button/ Button.tsx Button.stories.tsx ← 放在旁邊 Button.test.tsx 這樣的組織方式讓元件、Story、測試三者共同演化，刪除元件時不會遺留孤兒 Story 檔案。 撰寫有效的 Story 一個 Story 檔案通常包含：預設匯出（元件 metadata）+ 具名匯出（每個狀態）。好的 Story 設計原則是「一個狀態一個 Story」，而不是用一個 Story 加參數切換——因為命名的 Story 可以直接被測試框架引用。 import type { Meta, StoryObj } from '@storybook/react'; import { Button } from './Button'; const meta: Meta<typ

由 FeiYueh 親自審稿驗證 · 最後更新於 2026-05-19. Independently maintained — not AI-generated boilerplate.