hydration-guardian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hydration Guardian

Hydration 守护者

Overview

概述

Ensures zero-mismatch integrity between server-rendered HTML and client-side React trees. Covers hydration error diagnosis, selective hydration via Suspense boundaries, deterministic data bridges with the React 19

use()

hook,

'use cache'

for eliminating data drift, two-pass rendering for client-only content, React 19's single-diff hydration error reporting for pinpointing exact mismatches, and automated validation of rendered DOM state.

When to use: Debugging hydration mismatch errors, fixing text content mismatches, handling browser extension DOM pollution, implementing deterministic data bridges, optimizing SSR/client hydration performance, setting up error monitoring with

onRecoverableError

When NOT to use: Client-only React applications without SSR, static sites without hydration, API-only backends.

确保服务器渲染的HTML与客户端React树之间的零不匹配完整性。涵盖hydration错误诊断、通过Suspense边界实现选择性hydration、使用React 19的

use()

hook构建确定性数据桥接、利用

'use cache'

消除数据漂移、针对客户端专属内容的双阶段渲染、React 19的单差异hydration错误报告（可精确定位具体不匹配位置），以及渲染DOM状态的自动化验证。

适用场景： 调试hydration不匹配错误、修复文本内容不匹配问题、处理浏览器扩展导致的DOM污染、构建确定性数据桥接、优化SSR/客户端hydration性能、通过

onRecoverableError

设置错误监控。

不适用场景： 无SSR的纯客户端React应用、无需hydration的静态站点、仅提供API的后端服务。

Quick Reference

速查参考

Pattern	Approach	Key Points
Selective hydration	`<Suspense fallback={...}>` boundary	Hydrates independently; prioritizes user interaction
Deterministic bridge	`use(serverPromise)` instead of useEffect	Direct server-to-client data transition (React 19)
Cache directive	`'use cache'` in data fetchers	Share exact server result with client during hydration
Two-pass rendering	`useState` + `useEffect` for client-only	First render matches server; second adds client content
Client-only skip	`next/dynamic` with `ssr: false`	Exclude component from server render entirely
Error monitoring	`onRecoverableError` on `hydrateRoot`	Detect and report silent hydration recovery
Error reporting	React 19 single-diff error format	Pinpoints exact mismatch location with unified diff output
Error callbacks	`onUncaughtError` , `onCaughtError`	Granular error handling on `createRoot` / `hydrateRoot`
Date/time safety	UTC normalization or server-synced context	Prevent locale-dependent hydration mismatches
Extension resilience	Test with common browser extensions active	Detect DOM pollution from translators, dark-mode tools

模式	实现方式	核心要点
选择性hydration	`<Suspense fallback={...}>` 边界组件	独立进行hydration；优先响应用户交互
确定性数据桥接	使用 `use(serverPromise)` 替代useEffect	直接实现服务器到客户端的数据传输（React 19）
缓存指令	在数据获取函数中使用 `'use cache'`	在hydration过程中与客户端共享完全一致的服务器结果
双阶段渲染	结合 `useState` + `useEffect` 处理客户端专属内容	首次渲染与服务器输出匹配；第二次渲染添加客户端专属内容
跳过服务器渲染	配置 `next/dynamic` 并设置 `ssr: false`	完全将组件排除在服务器渲染流程之外
错误监控	在 `hydrateRoot` 上配置 `onRecoverableError`	检测并报告静默的hydration恢复事件
错误报告	React 19的单差异错误格式	通过统一的差异输出精确定位具体不匹配位置
错误回调	`onUncaughtError` 、 `onCaughtError`	在 `createRoot` / `hydrateRoot` 上实现精细化错误处理
日期/时间安全性	UTC标准化或服务器同步上下文	避免因区域设置差异导致的hydration不匹配
扩展兼容性	启用常见浏览器扩展进行测试	检测翻译工具、深色模式工具等导致的DOM污染

Hydration Error Diagnosis

Hydration错误诊断

Error Message	Likely Cause	Corrective Action
`Text content did not match`	Non-deterministic render (dates, random values)	Use two-pass rendering or `suppressHydrationWarning`
`Expected server HTML to contain`	Client renders content server did not	Move client-only code to `useEffect` or dynamic import
`Hydration failed`	Invalid HTML nesting ( `<p>` inside `<p>` )	Fix HTML structure; browsers auto-correct causing drift
`Extra attributes from server`	Server-only attributes not on client	Ensure attribute parity or use `suppressHydrationWarning`
`There was an error while hydrating`	Extension-modified DOM or major mismatch	Check for browser extensions; verify HTML validity

错误信息	可能原因	修正措施
`Text content did not match`	非确定性渲染（如日期、随机值）	使用双阶段渲染或 `suppressHydrationWarning`
`Expected server HTML to contain`	客户端渲染了服务器未输出的内容	将客户端专属代码移至 `useEffect` 或使用动态导入
`Hydration failed`	无效HTML嵌套（如 `<p>` 嵌套在 `<p>` 内）	修复HTML结构；浏览器会自动修正结构导致内容漂移
`Extra attributes from server`	服务器端存在客户端没有的属性	确保属性一致性或使用 `suppressHydrationWarning`
`There was an error while hydrating`	扩展修改DOM或严重内容不匹配	检查浏览器扩展；验证HTML有效性

Common Mistakes

常见误区

Mistake	Correct Pattern
Using `suppressHydrationWarning` on container elements	Fix the root cause; suppress only on leaf elements with unavoidable differences
Accessing `window` or `document` in the render body	Wrap client-only code in `useEffect` or use `next/dynamic` with `ssr: false`
Using `Math.random()` or `new Date()` without stable seeds	Use UTC normalization, server-cached values, or two-pass rendering
Ignoring silent hydration recovery in production	Configure `onRecoverableError` on `hydrateRoot` to log and monitor
Using `dangerouslySetInnerHTML` with server/client mismatch	Ensure identical content or use a dedicated `key` change to force remount
Checking `typeof window !== 'undefined'` in render	Use two-pass rendering; the check runs on server too (it returns false)
Nesting `<p>` inside `<p>` or `<div>` inside `<p>`	Fix invalid HTML nesting; browsers correct it causing server/client drift

错误做法	正确实现方案
在容器元素上使用 `suppressHydrationWarning`	修复根本问题；仅在存在不可避免差异的叶子元素上使用该属性
在渲染逻辑中直接访问 `window` 或 `document`	将客户端专属代码包裹在 `useEffect` 中，或使用 `next/dynamic` 并设置 `ssr: false`
未使用稳定种子的情况下使用 `Math.random()` 或 `new Date()`	使用UTC标准化、服务器缓存值或双阶段渲染
在生产环境中忽略静默的hydration恢复事件	在 `hydrateRoot` 上配置 `onRecoverableError` 以进行日志记录和监控
使用 `dangerouslySetInnerHTML` 时存在服务器/客户端内容不匹配	确保内容完全一致，或通过修改 `key` 强制组件重新挂载
在渲染逻辑中检查 `typeof window !== 'undefined'`	使用双阶段渲染；该检查在服务器端也会执行（返回false）
将 `<p>` 嵌套在 `<p>` 内或 `<div>` 嵌套在 `<p>` 内	修复无效HTML嵌套；浏览器会自动修正结构导致服务器与客户端内容漂移

Delegation

任务委派

Scan rendered pages for hidden hydration warnings: Use
```
Explore
```
agent with Chrome DevTools to run the hydration audit script
Fix hydration mismatches across multiple routes: Use
```
Task
```
agent to isolate, correct, and verify each affected component
Design hydration-safe architecture for new features: Use
```
Plan
```
agent to select between Suspense boundaries, two-pass rendering, and cache patterns

扫描渲染页面中的隐藏hydration警告：使用Explore工具结合Chrome DevTools运行hydration审计脚本
修复多路由下的hydration不匹配问题：使用Task工具隔离、修正并验证每个受影响的组件
为新功能设计hydration安全的架构：使用Plan工具在Suspense边界、双阶段渲染和缓存模式中选择合适方案

References

参考资料

Common Mismatches -- causes, diagnosis, and fixes for hydration mismatch errors including dates, locales, HTML nesting, and browser extensions
Selective Hydration -- Suspense-based selective hydration, streaming SSR, two-pass rendering, and client-only components
Use Cache Patterns -- data drift prevention, Next.js use cache directive, React 19 use() hook, deterministic data bridges
Validation Techniques -- automated DOM verification, mutation monitoring, onRecoverableError, and production hydration monitoring

常见不匹配问题 -- 涵盖日期、区域设置、HTML嵌套、浏览器扩展等导致的hydration不匹配错误的原因、诊断和修复方法
选择性Hydration -- 基于Suspense的选择性hydration、流式SSR、双阶段渲染和客户端专属组件
缓存模式使用 -- 数据漂移预防、Next.js use cache指令、React 19 use() hook、确定性数据桥接
验证技术 -- 自动化DOM验证、变更监控、onRecoverableError以及生产环境hydration监控