故障排查

沒有顯示路由

• 確認已安裝與應用路由器相符的配接器。
• 檢查 PageFlow 是否執行於開發伺服器，而非正式預覽。
• 對於沒有可檢查路由器的普通 Vite 設定，如果整合支援，請提供明確路由。

動態頁面無法開啟

在 dynamicParams 中加入安全範例值。確認路由模式，並直接開啟產生的 URL，以查看驗證或 loader 重新導向。

預覽保持空白或載入中

• 檢查應用主控台和網絡請求。
• 確認頁面能在目前瀏覽器工作階段中渲染。
• 等待必要的字型和圖片載入。
• 對於長時間非同步工作，頁面準備好後呼叫 window.__UNPLUGIN_PAGEFLOW_READY__?.()。

缺少導航

PageFlow 探索受支援的連結和字面量目標。計算得出的程式化目標可能只有在互動後才出現。Astro island 內部刻意不檢查；需要時請使用同源錨點或 data-pageflow-to。

縮圖已過期

讓擷取佇列更新可見頁面。如果快取已無用，停止開發伺服器並刪除 .unplugin-pageflow/cache。

顯示驗證頁面

驗證來自目前瀏覽器工作階段。在同一工作階段登入本機應用，或把預期的登入／拒絕存取頁面視為正確預覽。

測試未關聯

檢查自動關聯規則，然後加入明確的 pageTests 映射。只有為測試類型設定 testCommands 項目後，測試才能執行。

Next.js sidecar 失敗

確認應用正在執行、sidecar 的主機與連接埠可用，且兩個介面都使用預期的同源設定。請參閱 Next.js 指南。