トラブルシューティング

ルートが表示されない

• アプリケーションのルーターに合うアダプターをインストールしたか確認します。
• 本番プレビューではなく開発サーバーで PageFlow を実行します。
• ルーターを検査できない素の Vite 構成では、連携が対応していればルートを明示します。

動的ページが開かない

dynamicParams に安全なサンプル値を追加します。ルートパターンを確認し、生成 URL を直接開いて認証や loader のリダイレクトを調べます。

プレビューが空白または読み込み中のまま

• アプリケーションのコンソールとネットワークリクエストを確認します。
• 現在のブラウザーセッションでページを描画できるか確認します。
• 必要なフォントと画像を待ちます。
• 長い非同期処理では、準備完了時に window.__UNPLUGIN_PAGEFLOW_READY__?.() を呼びます。

遷移が見つからない

計算される遷移先は操作後にのみ現れる場合があります。Astro island の内部は検査しません。必要に応じて同一オリジンのアンカーまたは data-pageflow-to を使います。

サムネイルが古い

キャプチャキューの更新を待ちます。不要なキャッシュは開発サーバーを停止して .unplugin-pageflow/cache を削除します。

認証ページが表示される

認証は現在のブラウザーセッションを使います。同じセッションでローカルアプリへログインしてください。権限がない場合、ログインまたはアクセス拒否ページが正しいプレビューです。

テストが関連付けられない

自動規則を確認し、必要なら pageTests を明示します。種別に対応する testCommands がある場合だけ実行できます。

Next.js sidecar が失敗する

アプリが実行中で、sidecar のホストとポートが利用でき、同一オリジン設定が正しいか確認します。Next.js ガイドも参照してください。