從 Storybook 6.x 遷移到 8.0 的指南
Storybook 8 專注於提升效能、相容性與穩定性。主要功能包含
- 🩻 透過視覺化測試附加元件的全新視覺化測試工作流程
- 💨 測試建置速度提升 2-4 倍、React docgen 速度提升 25-50%，以及Webpack 專案的 SWC 支援
- 🧩 改善框架支援：當使用非 React 渲染器時，您不再需要安裝 React 作為同層級依賴
- 🎛️ 強化 React 和 Vue 專案中的控制項生成
- ⚡️ 改善 Vite 架構、Vitest 測試，以及 Vite 5 支援
- 🌐 支援 React Server Components (RSC)：我們的實驗性解決方案會在瀏覽器中渲染非同步 RSC 並模擬 Node 程式碼
- ✨ 煥然一新的桌面 UI 和行動 UX
- ➕ 還有更多、更多
本指南旨在協助您成功從 Storybook 6.x 升級到 8.0！
重大breaking changes
本指南的其餘部分將協助您成功升級，無論是自動或手動。但首先，我們在 Storybook 7 和 Storybook 8 中累積了許多 breaking changes。以下是您在繼續之前應了解的最具影響力的變更
framework欄位現在為必填- 已移除啟動和建置 CLI 二進制檔案
- 已移除
storiesOfAPI - 已移除
*.stories.mdx格式 - 套件已整合/移除
- 隱含 actions（來自
argTypesRegex）在渲染期間（例如在 play function 中）不再能使用 react-docgen（而非react-docgen-typescript）是組件分析的預設值- 已移除 Storyshots
- 現在需要 Storybook 7 中引入的 Addons API
- 生態系統更新
如果這些變更中有任何一項適用於您的專案，請在繼續之前詳閱連結的遷移注意事項。
如果這些新需求或變更中有任何一項阻礙了您的專案，我們建議您查看遷移到 Storybook 7 的需求。
您可能希望在遷移之前閱讀 Storybook 6 到 7 和 Storybook 7 到 8 的完整遷移注意事項。或者您可以按照以下指示操作，我們將盡力為您處理一切！
自動升級
若要升級您的 Storybook
npx storybook@latest upgrade這將會
- 判斷breaking changes 中是否有任何一項適用於您的專案
- 如果適用，您將收到關於如何在繼續之前解決這些問題的指示
- 將您的 Storybook 依賴項升級到最新版本
- 執行一系列自動遷移，這將會
- 檢查常見的升級任務
- 說明必要的變更，並提供更多資訊的連結
- 請求核准，然後代表您執行任務
常見升級問題
雖然我們會盡力自動升級您的專案，但有兩個問題值得一提，您在升級過程中可能會遇到
storyStoreV7:false 和 storiesOf
如果您的 .storybook/main.js 中有 storyStoreV7: false，您需要先移除它，才能升級到 Storybook 8。
如果您正在使用 storiesOf API（在 Storybook 7 中需要 storyStoreV7: false），您需要將您的 stories 遷移到 CSF，或使用新的 indexer API 以繼續動態建立 stories。
MDX 1 到 MDX 3
Storybook 8 使用 MDX 3。如果您是從 MDX 1（Storybook 6 使用）升級，MDX 2 中有重大的 breaking changes。請參考我們的關於成功升級的指南。
遺失 vite.config.js 檔案
如果您正在使用 Vite，您現在可能需要在專案根目錄中建立 vite.config.js 檔案，以允許較新版本的 Vite 與 Storybook 協同運作。此外，您可能需要為您的框架安裝和設定 Vite 外掛程式。更多資訊請參閱完整遷移注意事項。
套件結構變更
以下套件已被移除。有關詳細資訊，請參閱完整遷移注意事項。
| 移除 | 取代 |
|---|---|
@storybook/addons | @storybook/manager-api 或 @storyboook/preview-api |
@storybook/channel-postmessage | @storybook/channels |
@storybook/channel-websocket | @storybook/channels |
@storybook/client-api | @storybook/preview-api |
@storybook/core-client | @storybook/preview-api |
@storybook/preview-web | @storybook/preview-api |
@storybook/store | @storybook/preview-api |
@storybook/api | @storybook/manager-api |
以下套件已被棄用。有關詳細資訊，請參閱完整遷移注意事項。
| 棄用 | 取代 |
|---|---|
@storybook/testing-library | @storybook/test |
疑難排解
自動升級應使您的 Storybook 進入可運作狀態。如果您在升級後執行 Storybook 時遇到錯誤，以下是您應執行的操作
- 嘗試執行
doctor命令，以檢查常見問題（例如重複的依賴項、不相容的附加元件或不匹配的版本），並查看修復建議。 - 如果您使用
dev命令執行storybook，請嘗試改用build命令。有時build錯誤比dev錯誤更易於理解！ - 查看完整遷移注意事項，其中包含 Storybook 8 中值得注意的變更的完整列表。當您升級時，其中許多變更已由自動遷移處理，但並非全部。您也可能遇到我們未意識到的邊緣情況。
- 在 GitHub 上的 Storybook issues 中搜尋。如果您遇到問題，很有可能其他人也遇到了。如果是這樣，請為該 issue 投票，嘗試評論中描述的任何解決方法，如果您有有用的資訊要貢獻，請回覆評論。
- 如果沒有現有的 issue，您可以提交一個，最好附上重現步驟。在我們穩定發布版本時，我們將密切關注 Storybook 8 的 issues。
如果您喜歡自行偵錯，以下是一些有用的方法，可以幫助您縮小問題範圍
- 嘗試移除所有不在
@storybooknpm 命名空間中的附加元件（請確保您沒有移除storybook套件）。與 7.x 良好協同運作的社群附加元件可能尚未與 8.0 相容，這是隔離這種可能性的最快方法。如果您發現需要升級附加元件才能與 Storybook 8 協同運作，請在該附加元件的儲存庫上發布 issue，或更好的是，提交 pull request 以升級它！ - 另一種偵錯技術是二分搜尋到較舊的 Storybook 預發布版本，以找出哪個版本破壞了您的 Storybook。例如，假設目前 Storybook 的預發布版本是
8.0.0-beta.56，您可以將版本設定為8.0.0-alpha.0在您的package.json中並重新安裝以驗證它是否仍然有效（alpha.0應該與7.6.x幾乎相同）。如果有效，您可以嘗試8.0.0-beta.0，然後是8.0.0-beta.28，依此類推。一旦您隔離了錯誤的版本，請閱讀其變更日誌條目，也許有一個變更會突出顯示為罪魁禍首。如果您發現問題，請提交 issue 或 pull request 到 Storybook monorepo，我們將盡力快速處理。
可選的遷移
除了上述的自動遷移和手動遷移之外，還有您應該考慮的可選遷移。這些是我們在 Storybook 7 和 8 中棄用的功能（但保持向後相容），或是應該能幫助您在未來更有效率的最佳實務。
CSF 2 到 CSF 3
將您的 stories 從 CSF 2 轉換為 CSF 3 有許多充分的理由。我們提供了一個 codemod，在大多數情況下，它應該會自動為您進行程式碼變更（請確保更新 glob 以符合您的檔案）
# Convert CSF 2 to CSF 3
npx storybook@latest migrate csf-2-to-3 --glob="**/*.stories.tsx" --parser=tsx