SuperAPI AI 工具集

ssr-hydration-mismatch

通用与其它

查看项目

更新于 10-16 06:44

技能介绍

用途:诊断并修复 SSR 水合不匹配(hydration mismatch)。当服务端渲染的 HTML 与客户端首次渲染结果不一致时,框架会丢弃服务端树并在客户端重渲染,SSR 收益丢失,还会出现闪烁;React 18+ 还会抛出可恢复错误。

主要能力:给出触发条件清单——首次渲染不确定(Date.now()、Math.random()、new Date()、locale/时区格式化、typeof window 分支)、客户端独有值写在首次渲染中、HTML 嵌套非法(如 <p> 内嵌 <div>、<table> 下直接放文本)导致浏览器解析修复。提供修复方向:挂载后再取客户端值(useEffect 两遍渲染、useSyncExternalStore 带服务端快照)、为 SSR 文本固定 locale/timeZone、用 <Suspense> 或 ssr:false 的动态导入隔离纯客户端 UI;说明 suppressHydrationWarning 仅作用于单层自身文本/属性,非万能解法;建议将 hydrateRoot 的 onRecoverableError 接入监控并配 source map。

使用方式:先确认组件参与 SSR 或初始 HTML 生成,指出具体的服务端/客户端首渲染差异值,用水合冒烟测试、onRecoverableError 或 dev 警告取证,再给出最小修复和能捕获该不匹配的测试。

适用场景:React/Next 为主,Vue/Nuxt(<ClientOnly>)、Svelte/SvelteKit、Astro(client:only)为同类逃生口。

限制:仅适用于能关联到 SSR 路径的发现;事件处理器、effect、仅服务端代码中的随机/时间不影响客户端首渲染,应判为“确定性清理”而非水合 bug;挂载后、useEffect 内或 ssr:false 下的 locale 格式化不算问题。时区/语言依赖文本的另一修复位于 datetime-correctness,路由参数水合就绪见 deeplink-hydration。