故障排查

没有发现路由

• 确认安装了与应用路由器匹配的适配器。
• 确认 PageFlow 运行在开发服务器，而不是生产预览中。
• 对无法检查路由器的普通 Vite 应用，根据集成能力提供显式路由。

动态页面打不开

通过 dynamicParams 添加安全示例值。检查路由模式，并直接打开生成的 URL，排除身份认证或 Loader 重定向。

页面空白或一直加载

• 检查应用控制台和网络请求。
• 确认当前浏览器会话可以正常渲染该页面。
• 等待所需字体和图片加载。
• 长时间异步任务完成后调用 window.__UNPLUGIN_PAGEFLOW_READY__?.()。

没有显示导航连接

PageFlow 会发现受支持的链接和字面量目标。动态计算的程序式目标可能要等交互发生后才出现。Astro 不检查 Island 内部实现，必要时使用同源链接或 data-pageflow-to。

缩略图没有更新

等待捕获队列刷新可见页面。缓存不再有效时，停止开发服务器并删除 .unplugin-pageflow/cache。

总是显示登录页

身份认证来自当前浏览器会话。请在同一会话中登录本地应用；如果没有权限，登录或拒绝访问页面就是准确预览结果。

测试没有关联

先检查自动关联规则，再添加显式 pageTests 映射。测试类型只有配置了对应 testCommands 后才能运行。

Next.js sidecar 无法启动

确认应用已启动、Host 和端口可用，并检查同源设置。参见 Next.js 接入指南。