Starlight 0.42 升級要檢查什麼？Popover、JavaScript 與 sidebar

0.42 這次真正會影響什麼#

Astro 官方在大型、深層 sidebar 的情境下報告過最高約 1,400 倍的資料處理速度改善；這是特定基準測試的上限，不是每個網站的保證值。升級仍應以自己的 build 時間與輸出回歸為準。

先用升級工具，再看完整 diff#

官方文章建議既有 Starlight 專案使用 @astrojs/upgrade。ZeroOne 使用 pnpm，因此可以在專案根目錄執行：

1
pnpm dlx @astrojs/upgrade

也可以使用官方文件中的等價指令：

1
npx @astrojs/upgrade

升級工具可能同時更新 Starlight、Astro 與 integrations。執行後先看 diff，不要把所有 package 更新視為同一個無風險變更：

1
git diff -- package.json pnpm-lock.yaml astro.config.mjs
2
pnpm check
3
pnpm build

如果專案還在 Astro 5 或 Astro 6，先閱讀 Astro 7 升級清單 的 major migration 風險，再決定是否把 Astro major 與 Starlight 0.42 放在同一次變更。分開升級能讓 compiler、integration 和文件主題的問題比較容易定位。

行動版選單：測試 Popover，不要只測滑鼠點擊#

Starlight 0.42 的行動版選單改用 Popover API。這表示基礎開關行為交給瀏覽器的原生互動模型處理，官方也特別指出，即使 JavaScript 失效或被停用，選單仍應能運作。若想先理解 popover、auto 和 manual 的差異，可參考 HTML Popover API 的實作與除錯。

升級後至少做以下測試：

1. 寬度切到行動版，開啟與關閉主選單、巢狀選單和搜尋入口。
2. 用鍵盤 Tab 進入選單、以 Escape 關閉，再確認焦點回到合理的觸發按鈕。
3. 暫時停用 JavaScript，確認基本導覽仍能展開、關閉與前往連結。
4. 開啟瀏覽器的 accessibility tree 或 keyboard navigation，檢查自訂 wrapper 沒有遮住 Popover 的互動元素。
5. 抽查直接開啟深層文章、返回上一頁和重新整理後，選單狀態沒有卡住。

如果專案自行覆寫 Starlight 的 menu CSS、掛載 click listener，或透過 DOM selector 加入動畫，這些才是最可能需要修正的地方。不要為了保留舊 selector 而把新選單再包一層全域 click handler，先確認是否和原生 Popover 的開關及焦點行為衝突。

編譯後 JavaScript：把 typecheck 當成升級檢查#

0.42 開始，Starlight 編譯套件來源，並發布 JavaScript 與型別定義，而不是把 TypeScript 原始碼直接交給使用者的工具鏈。這可能降低大型專案 typecheck 的負擔，但不代表專案的型別問題會自動消失。

若文件站有自訂 theme component、MDX component 或 integration，升級後應檢查：

• import 是否仍指向公開的套件入口，而不是套件內部的 TypeScript 路徑；
• astro check／pnpm check 是否仍能解析自訂 component props；
• 自訂型別 augmentation、tsconfig path alias 和 ESLint／Biome 的 resolver 是否仍指向正確檔案；
• build 產出的 client script 是否保留互動元件，沒有因 tree-shaking 或 import 變更而消失。

遇到型別錯誤時，先將套件版本與應用程式程式碼的修改拆開。先確認錯誤是公開型別入口改變、舊版 internal import，還是自己的 component contract 不再符合，再決定是否加 compatibility layer。

大型 sidebar：速度改善不能取代導覽回歸#

sidebar 的速度改善主要對大型、深層、含大量頁面的文件站有價值。小型站點可能幾乎感覺不到差異，但仍要確認升級沒有改變內容排序或 active state。

可以用以下方式做可重現比較：

1
time pnpm build
2
time pnpm build

第二次 build 不能代替 clean build；請在相同 Node、pnpm、lockfile 與 CI runner 條件下，比較乾淨建置、第二次建置與修改單一文件後的建置。速度數字只回答處理時間，還要另外抽查：

一份可以回滾的升級清單#

升級 Starlight 前後，建議留下同一組 baseline 與 smoke test：

1. 記錄目前 @astrojs/starlight、Astro、Node、pnpm 與 lockfile 狀態。
2. 用升級工具產生 package diff，只保留本次預期的版本變更。
3. 跑 pnpm check 與 pnpm build，保存錯誤輸出和建置時間。
4. 測試行動版 Popover、鍵盤焦點、Escape、停用 JavaScript 和自訂 menu CSS／script。
5. 抽查 sidebar 的巢狀層級、多語路徑、active state、深層文章與重新命名後的連結。
6. 確認頁面 HTML、canonical、sitemap、搜尋索引、local cover 和 RSS 輸出沒有非預期變化。
7. 把 package diff 與測試結果放在同一個 commit，若失敗可只回滾 Starlight 變更。

如果站點沒有覆寫主選單，也沒有大型 sidebar，實際程式碼變更可能很少；但 pnpm check、pnpm build 和行動版人工測試仍不能省略。這次升級的價值在於採用新的互動與套件發布方式，同時確認自己的整合沒有依賴舊實作細節。

Starlight 0.42 的升級重點可以濃縮成三個檢查：先讀版本 diff，再驗證 Popover 和 keyboard accessibility，最後用自己的 sidebar 與 build 結果確認效能改善。看到官方的 1,400 倍基準時，應把它當成測試方向，而不是把數字直接寫進專案 SLA。

常見問題#