安裝 Storybook

使用 Storybook CLI 以單一指令安裝。在專案根目錄內執行此指令

npx storybook@latest init

安裝特定版本

init 命令會使用您指定的任何版本。例如

storybook@latest init 會初始化最新版本
storybook@7.6.10 init 會初始化 7.6.10
storybook@7 init 會初始化最新的 7.x.x 版本

Storybook 會在其安裝過程中檢查您專案的相依性，並為您提供最佳的可用設定。

上面的指令會對您的本機環境進行以下變更

📦 安裝所需的相依性。
🛠 設定執行和建構 Storybook 的必要指令碼。
🛠 新增預設的 Storybook 設定。
📝 新增一些樣板 stories 讓您開始使用。
📡 設定遙測以協助我們改善 Storybook。在此處閱讀更多相關資訊 here。

觀看影片教學

執行設定精靈

如果一切順利，您應該會看到一個設定精靈，它會協助您開始使用 Storybook，向您介紹主要概念和功能，包括 UI 的組織方式、如何撰寫您的第一個 story，以及如何使用控制項測試元件對各種輸入的反應。

Storybook onboarding

如果您跳過了精靈，您可以隨時將 ?path=/onboarding 查詢參數新增至您的 Storybook 執行個體的 URL 來再次執行，前提是範例 stories 仍然可用。

啟動 Storybook

Storybook 隨附內建的開發伺服器，其中包含專案開發所需的一切。根據您的系統設定，執行 storybook 命令會啟動本機開發伺服器，為您輸出位址，並自動在新的瀏覽器索引標籤中開啟該位址，歡迎畫面會在其中迎接您。

npm run storybook

Storybook 會收集完全匿名的資料，以協助我們改善使用者體驗。參與是可選的，如果您不想分享任何資訊，您可以選擇退出。

Storybook welcome screen

這裡有一些值得注意的項目

一組有用的連結，可讓您深入瞭解您可用的更多設定和自訂選項。
第二組連結，供您擴展 Storybook 知識並參與不斷發展的 Storybook 社群。
一些範例 stories 讓您開始使用。

疑難排解

使用其他套件管理員執行 Storybook

Storybook CLI 包含對業界熱門套件管理員（例如，Yarn、npm 和 pnpm）的支援，在您初始化 Storybook 時會自動偵測您正在使用的套件管理員。但是，如果您想要將特定的套件管理員設為預設值，請將 --package-manager 旗標新增至安裝命令。例如

npx storybook@latest init --package-manager=npm

CLI 無法偵測到我的框架

如果您使用的是自訂環境設定，或是需要手動設定 Storybook，您可以使用 --type 旗標來指定您需要使用的框架。以下列出支援的框架以及如何使用它們的範例

框架	類型
Angular	`angular`
Ember	`ember`
HTML	`html`
Next.js	`nextjs`
Preact	`preact`
Qwik	`qwik`
React	`react`
Server	`server`
Solid	`solid`
Svelte	`svelte`
Vue 3	`vue3`
Web Components	`web_components`

npx storybook@latest init --type solid

Storybook 對 Yarn Plug'n'Play (PnP) 的支援

如果您在啟用 Plug'n'Play (PnP) 的新版 Yarn 專案中啟用了 Storybook，您可能會注意到它會產生包含一些額外檔案和資料夾的 node_modules。這是一個已知的限制，因為 Storybook 依賴某些目錄（例如，.cache）來儲存快取檔案和其他資料，以提高效能和加速建置。您可以安全地忽略這些檔案和資料夾，並調整您的 .gitignore 檔案，將它們排除在您正在使用的版本控制之外。

使用 Webpack 4 執行 Storybook

如果您先前在使用了 Webpack 4 的專案中安裝了 Storybook，它將無法再運作。這是因為 Storybook 現在預設使用 Webpack 5。為了解決這個問題，我們建議您將專案升級到 Webpack 5，然後執行以下命令將您的專案遷移到最新版本的 Storybook

npx storybook@latest automigrate

安裝過程似乎不穩定且持續失敗

如果您在安裝過程中仍然遇到問題，我們建議您查看以下資源

Storybook 的 React Webpack README，以取得更多關於如何在您的 React 專案中設定使用 Webpack 5 的 Storybook 的資訊。
Storybook 的 React Vite README，以取得更多關於如何在您的 React 專案中設定使用 Vite 的 Storybook 的資訊。
Storybook 的協助文件，以聯絡社群並尋求協助。

既然您已成功安裝 Storybook 並了解其運作方式，讓我們繼續在設定精靈中未完成的部分，並深入研究撰寫 stories。