從 Storybook 6.x 遷移至 8.0 的遷移指南
Storybook 8 專注於提升效能、相容性和穩定性。主要功能包括：
- 🩻 透過 視覺測試外掛 的全新視覺測試工作流程
- 💨 速度快 2-4 倍的測試建置、速度快 25-50% 的 React docgen，以及 Webpack 專案的 SWC 支援
- 🧩 改善的框架支援：使用非 React 渲染器時，不再需要安裝 React 作為對等相依性
- 🎛️ 在 React 和 Vue 專案中加強的控制項產生
- ⚡️ 改善的 Vite 架構、Vitest 測試和 Vite 5 支援
- 🌐 支援 React 伺服器元件 (RSC)：我們的實驗性解決方案會在瀏覽器中渲染非同步 RSC，並模擬 Node 程式碼
- ✨ 更新的桌面 UI 和行動 UX
- ➕ 還有更多
本指南旨在協助您從 Storybook 6.x 成功升級至 8.0！
重大變更
本指南的其餘部分將協助您成功升級，無論是自動或手動升級。但首先，我們在 Storybook 7 和 Storybook 8 中累積了許多重大變更。以下是您在繼續之前應了解的最具影響力的變更
framework欄位現在是必要欄位- 移除啟動和建置 CLI 二進位檔
storiesOfAPI 已移除*.stories.mdx格式已移除- 套件已合併/移除
- 隱含動作（來自
argTypesRegex）在渲染期間（例如，在 play 函式中）無法再使用 react-docgen（而不是react-docgen-typescript）是元件分析的預設值- Storyshots 已移除
- 現在需要 Storybook 7 中引入的外掛 API
- 生態系統更新
如果這些變更中的任何一項適用於您的專案，請在繼續之前閱讀連結的遷移注意事項。
如果這些新需求或變更對您的專案造成阻礙，我們建議您查看遷移至 Storybook 7 的需求。
您可能會想在遷移之前閱讀 Storybook 6 至 7 和 Storybook 7 至 8 的完整遷移注意事項。或者您可以按照以下指示操作，我們將盡力為您處理一切！
自動升級
若要升級您的 Storybook
npx storybook@latest upgrade這會
- 判斷 重大變更 中沒有任何一項適用於您的專案
- 如果適用，您將收到關於如何在繼續之前解決這些問題的指示
- 將您的 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 中有重大的變更。請參考我們的關於成功升級的指南。
缺少 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 問題。如果您看到問題，很可能其他人也遇到了。如果是這樣，請對該問題投贊成票，嘗試評論中描述的任何變通方法，如果您有可貢獻的有用資訊，請回覆評論。
- 如果沒有現有的問題，您可以提交一個問題，最好附上重現步驟。我們會在穩定發佈的過程中密切關注 Storybook 8 的問題。
如果您喜歡自己除錯，以下是一些有助於縮小問題範圍的實用方法
- 嘗試移除所有不在
@storybooknpm 命名空間中的附加元件（請確保您不要移除storybook套件）。與 7.x 版本搭配良好的社群附加元件可能尚未與 8.0 相容，這是隔離該可能性的最快方法。如果您發現需要升級才能與 Storybook 8 搭配使用的附加元件，請在該附加元件的儲存庫上張貼問題，或者更好的是，發送一個升級它的 pull request！ - 另一種除錯技術是將 Storybook 切割到較舊的預發佈版本，以找出哪個版本損壞了您的 Storybook。例如，假設目前 Storybook 的預發佈版本是
8.0.0-beta.56，您可以在package.json中將版本設定為8.0.0-alpha.0並重新安裝以驗證它是否仍然有效（alpha.0應該與7.6.x幾乎相同）。如果它有效，您可以嘗試8.0.0-beta.0，然後是8.0.0-beta.28，依此類推。一旦您隔離了錯誤的版本，請閱讀其變更日誌條目，也許會有一個變更跳出來是罪魁禍首。如果您發現問題，請向 Storybook monorepo 提交一個問題或 pull request，我們會盡力快速處理。
可選的遷移
除了上述的自動遷移和手動遷移之外，還有一些您應該考慮的可選遷移。這些是我們在 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