用途:解决深链接进入 SPA/SSR 页面时,query 参数丢失或首屏落到错误页面的问题。核心是 URL 必须能独立重建页面,而路由状态在水合前滞后于真实 URL。
主要能力:识别并规避首屏渲染期间依赖参数的逻辑(重定向、回退、埋点、参数缺失即回首页的守卫)在空状态下误动作;强调在参数已知前不得执行重定向。
用法要点:Next.js Pages Router 用 useEffect 中的 router.isReady 门控;Vue Router 用 router.isReady();React Router 无等价就绪标志,使用 useLocation()/useParams()/loader 数据,把延迟网络数据视为数据就绪而非参数水合;Next.js App Router 无 router.isReady,useSearchParams() 在客户端组件同步,但会将子树推入最近的 Suspense 边界,因此用 Suspense 包裹读取参数的组件并以骨架屏兜底。路由器滞后时以 window.location.pathname/.search 为客户端事实来源;SSR 下需延后到挂载后读取。
限制与场景:纯 CSR 可在首屏读 window.location;SSR 下的 typeof window 守卫本身会触发水合不一致,另见 ssr-hydration-mismatch。认证跳转需携带并恢复目标地址(returnTo 等),具体归 frontend-auth-flow-contracts 与 frontend-security-baseline。每个可深链页面需冷启动直达测试,等待最终 URL。参数解析每页归一到一个函数。排除应用内导航、URL 中确实缺失参数、SSR DOM 分歧、认证开放重定向等弱发现。