在SSR体系里，用户拿到的首屏内容往往是一段已经“长得像页面”的HTML。它能被浏览器立刻解析成DOM并绘制到屏幕上，但此时页面依然像一张“干的照片”：看得到，却不一定点得动。hydration的任务，就是把这张静态快照变成真正能响应交互的应用，把组件逻辑、事件处理、状态管理接回到浏览器端运行。React 文档用非常直白的措辞描述了这件事：hydration会把组件逻辑“附着”到服务端生成的初始HTML上，让它变成可交互的应用。(React)
为了把hydration讲透，下面我会用“浏览器真实发生了什么”的视角，把它拆成几个层次：网络与解析层、框架运行时层、事件系统层、状态与副作用层、异常与性能层。阅读时你会发现，hydration并不是一个单一动作，更像一串精密的对齐与接管流程。
一、hydration出现的前提：你已经做了SSR，并且准备在客户端再跑一遍框架
把典型的SSR + hydration请求路径压缩成一句话：
服务端把 UI 渲染成
HTML发给浏览器，浏览器先显示出来；客户端脚本加载后，框架在同一棵DOM上建立内部数据结构与事件系统，尽量复用现有节点并接管后续更新。
web.dev 在讨论server-side rendering with rehydration时强调了一个关键事实：页面可能“看起来已经加载完成”，但在组件脚本执行、事件处理器真正挂载之前，它并不能响应输入，这会让用户非常困惑。(web.dev)
这句话其实点出了hydration的核心矛盾：要快（先把内容给用户看到），也要真（最终必须变成可交互应用）。把这两件事拼起来，就需要一段“接管期”，而hydration就是这段接管期的名字。
二、从时间线看hydration：浏览器里按顺序发生的事情
下面这条时间线非常贴近你在Chrome DevTools里看到的真实顺序：
1）浏览器拿到服务端返回的HTML，立刻解析并绘制
- 网络层收到
document响应 HTML parser流式解析，边解析边构建DOM- 如果遇到
link rel=stylesheet，会触发CSS下载与解析 DOM + CSSOM形成渲染树，进入layout、paint、composite
这一段与任何传统多页站点没有本质差异，也是SSR能让FCP更快的根源：浏览器不需要等大段JavaScript执行才有内容可画。(web.dev)
2）浏览器下载并执行客户端JavaScript，框架运行时启动
当React、Next.js或其他框架的客户端包开始执行，hydration才真正进入舞台。以 React 为例，客户端会调用hydrateRoot(container, <App />)，告诉 React：container里已经有服务端渲染的HTML，请不要像纯CSR那样整棵重建，而是进入hydration模式去复用与对齐。(React)
3）框架把“组件树”与“现有 DOM”对齐，建立内部结构并挂上事件
这一步是hydration的技术核心：不是简单地addEventListener，也不是简单地重新渲染，而是在已有DOM上建立一套可更新的内部表示（React 里对应Fiber tree），同时把事件系统、状态、更新调度都接上。
只要这一步完成，页面从“能看”进入“能用”。
三、hydration的内核动作拆解：对齐、复用、接管
把hydration想象成“接管一座已经建好的房子”。服务端把墙和门都盖好了（HTML），但电路与智能系统还没装（事件、状态、更新）。客户端要做的事，是在不拆房子的前提下，把电路一点点接进去，并确认每个开关对应的灯确实在那个位置。
下面按内部动作拆开讲。
动作 A：创建root与运行时上下文，进入hydration模式
React 的入口是hydrateRoot。它和createRoot很像，但语义不同：hydrateRoot明确告诉 React 容器里已有由ReactDOMServer生成的HTML，需要“附着”逻辑而不是重绘。(React)
这一步会建立一组非常关键的运行时对象：
- 根容器与调度器（后续更新怎么排队、怎么分片、怎么中断与恢复）
- 事件系统的入口（合成事件、委托、优先级）
- 将要构建的组件内部树（React 是
Fiber）
你可以把它理解成：框架在浏览器里先搭一个“指挥部”。
动作 B：在客户端“再渲染一次组件树”，但目标不是生成新 DOM，而是生成“期望的结构”
很多人听到“再渲染一次”会以为重复浪费。事实是：客户端必须生成一份“我认为页面应该长什么样”的描述，否则它无法验证服务端给的HTML是否匹配，也无法建立从组件到真实节点的映射关系。
以 React 为例，客户端会执行组件函数，得到虚拟树；接着进入hydration reconciliation：拿虚拟树的节点与已有DOM节点做逐个匹配。
这也是为什么hydration对一致性极度敏感：服务端渲染出来的结构，必须与客户端首轮渲染的结构一致，否则匹配会失败，框架只能报警甚至局部放弃复用。
动作 C：DOM 节点复用与“绑定关系”建立
匹配成功时，框架会做两类绑定：
- 从组件节点到真实 DOM 的引用绑定：以后组件更新时知道该改哪个真实节点
- 从真实 DOM 到组件实例的反向关联：事件冒泡上来时，能从目标节点追溯到对应的组件监听器
这一步在工程上非常关键：它决定了后续更新是不是diff级别的增量修改，而不是整棵替换。
Gatsby 的文档在解释 Reacthydration时也提到，React 会尝试在现有标记上附加事件监听器，让站点从静态HTML转为完整 React 应用。(Gatsby)
动作 D：事件系统接管：你以为是给按钮绑onClick，实际常常是“根节点委托 + 运行时分发”
很多现代框架不会给每个按钮都单独addEventListener。React 的合成事件系统通常采用事件委托：在根容器上挂少量监听器，事件触发时通过运行时逻辑找到对应组件的回调并执行。
hydration阶段的意义在于：把这些回调的映射关系建好。服务端输出的HTML里不可能包含真实的函数引用，因此按钮看起来存在，但点击时没有任何 JS 逻辑能跑。hydration完成后，事件系统才知道这个<button>对应组件树里的哪个onClick。
web.dev 那句“看起来可交互但实际上不能响应输入，直到事件处理器被附着”说的就是这件事。(web.dev)
动作 E：状态初始化与一次性数据对齐
如果页面包含状态（例如购物车数量、登录用户信息），服务端渲染时用到的数据需要在客户端也能拿到，否则客户端首轮渲染就会“长得不一样”。
真实项目里常见做法是：
- 服务端把初始数据序列化到页面中（例如挂在
window.__INITIAL_DATA__） - 客户端启动时读取该数据，用它作为首轮渲染的数据源
只要两边用的是同一份数据，组件树结构就更容易一致，hydration更稳定。
动作 F：副作用与布局相关逻辑的时机差异
在 React 中，useEffect与useLayoutEffect的执行时机不同。hydration期间，框架通常会尽量避免破坏已存在的 DOM 结构，但副作用仍然会在合适时机触发：
- 布局相关的副作用（例如测量元素尺寸）若执行过早，可能造成抖动
- 数据拉取副作用若不做去重，可能导致“服务端拉一次、客户端再拉一次”
这也是SSR + hydration容易踩到的工程坑：你既想利用服务端提前拿数据，又不想在客户端重复成本。
四、一个最小可运行的例子：同一颗按钮，服务端能渲染，客户端才能点击
下面用最小 ReactSSR + hydration例子把抽象流程具体化。这个例子刻意保持简洁：服务端返回一个带按钮的HTML，按钮文字可见；客户端hydrateRoot之后按钮才真正可点。
说明：示例代码使用单引号与反引号，避免出现英文双引号。
1）server.js：服务端渲染出HTML
// server.jsimportexpressfrom'express'importReactfrom'react'import{renderToString}from'react-dom/server'importAppfrom'./src/App.js'constapp=express()app.use('/static',express.static('static'))app.get('/',(req,res)=>{consthtml=renderToString(React.createElement(App,{initialCount:1}))res.send(`<!doctype html> <html lang='zh'> <head> <meta charset='utf-8' /> <meta name='viewport' content='width=device-width, initial-scale=1' /> <title>SSR with hydration demo</title> </head> <body> <div id='root'>${html}</div> <script> window.__INITIAL_PROPS__ = { initialCount: 1 } </script> <script type='module' src='/static/client.js'></script> </body> </html>`)})app.listen(3000,()=>{console.log('listening on http://localhost:3000')})2）src/App.js：组件里有交互逻辑
// src/App.jsimportReact,{useState}from'react'exportdefaultfunctionApp(props){const[count,setCount]=useState(props.initialCount??0)return(React.createElement('div',null,React.createElement('p',null,`当前 count：${count}`),React.createElement('button',{onClick:()=>setCount(count+1)},'点我 +1')))}3）static/client.js：客户端做hydrateRoot
// static/client.jsimportReactfrom'react'import{hydrateRoot}from'react-dom/client'importAppfrom'../src/App.js'constprops=window.__INITIAL_PROPS__??{initialCount:0}hydrateRoot(document.getElementById('root'),React.createElement(App,props))这个例子里，有一个极容易验证的现象：
- 服务端返回后，
HTML里已经有button与p，用户立刻能看到当前 count：1 - 在客户端脚本还没加载完之前，点击按钮不会触发
setCount - 当
hydrateRoot运行并完成对齐后，按钮点击才会生效
这正对应 React 文档的定义：hydration会把组件逻辑附着到服务端生成的HTML上，让快照变成交互式应用。(React)
五、为什么会出现hydration mismatch：对齐失败时框架到底在抱怨什么
hydration mismatch的本质非常朴素：客户端首轮渲染出来的“期望结构”与服务端给的HTML不一致。Next.js 专门有一页文档解释react hydration error，并给出常见原因与处理方式。(Next.js)
常见触发源：时间、随机数、地区格式、仅客户端信息
这类问题的共同点是：服务端与客户端在首轮渲染时得到的值不同。
- 服务端渲染
Date.now()，客户端渲染时刻已经变了 - 服务端渲染
Math.random()，客户端永远不可能一致 - 服务端按
en-US格式化数字，客户端按用户浏览器语言格式化 - 服务端拿不到
window.innerWidth，客户端拿得到
一旦这些差异影响了文本内容、属性值、节点结构，React 在hydration时就会发现对不上，进而报错或回退到更保守的策略（例如丢弃某段复用，重新生成）。
一个真实可感知的例子：商品页的倒计时与库存跳动
电商详情页经常有倒计时、实时库存、实时在线人数。如果你在服务端把倒计时剩余秒数直接写进HTML，客户端启动时可能已经过了几秒。哪怕只差 1 秒，文本都不一致，就会触发hydration mismatch。
Next.js 文档给出了一种“确实不可避免时”的处理方式：对某些元素使用suppressHydrationWarning来抑制警告，例如时间戳这种天然会变的内容。(Next.js)
更工程化的做法是把这类内容改为“客户端接管后再更新”：
- 服务端输出一个稳定占位值，确保结构一致
- 客户端在
useEffect里启动定时器更新文本
这样牺牲了几秒的准确性，却换来hydration的稳定与更少的回退成本。
六、性能视角：hydration为什么会伤INP与TBT，以及怎么缓解
很多团队做SSR是为了更快的首屏内容展示，但如果hydration代价过高，页面会陷入一种“看起来好了，点起来卡”的状态。web.dev 明确指出：带rehydration的SSR可能显著负面影响TBT与INP，即使它改善了FCP。(web.dev)
这里的机制很清晰：
hydration需要下载、解析、执行客户端脚本- 需要遍历并匹配现有
DOM - 需要建立组件内部结构、事件映射、调度器
- 需要运行部分副作用与布局相关逻辑
这些都压在浏览器主线程上，主线程忙时用户的输入无法及时被处理，INP就会变差。
一个很有代表性的行业案例：选择性hydration与Suspense
Vercel 在介绍React 18与Suspense时提到，他们在 nextjs.org 上通过选择性hydration等手段把TBT从 430 ms 降到 80 ms，并同时验证了对交互指标的改善。(Vercel)
这类优化思路的核心是：别把整页一次性都水合。用户真正要点的通常是首屏按钮、菜单、搜索框；页脚、推荐列表、复杂图表可以延后。
渐进式hydration：把接管拆成块
patterns.dev 把这类思路总结为progressive hydration：仍然享受SSR的首屏优势，同时通过拆分与延迟降低hydration成本。(Patterns)
把它落到页面结构上，会长得像这样：
Header与Hero CTA：优先水合，保证立刻可点Below the fold的推荐区：等空闲或滚动到可视区再水合Footer：甚至可以不水合，保持静态
事件回放event replay：用户早点击了也不丢
另一个用户体验坑是：页面内容已经出来，但hydration尚未完成时用户点击了按钮，这次点击可能被丢掉。Angular 的hydration指南里专门描述了Event Replay：在hydration完成前捕获用户交互，待水合结束后再回放，确保交互不会丢失。(Angular)
即便你不用 Angular，这个概念依然很值得借鉴：它本质是在解决“接管期的交互一致性”。
七、以 Next.js 为例：use client、组件边界与hydration的关系
在 Next.js 的 App Router 体系里，组件默认是 Server Component，只有显式标记use client的组件才会进入客户端包并参与hydration。Next.js 文档把它描述为一种边界声明：use client用来划分 Server 与 Client 模块图，一旦标记，相关依赖与子组件都会进入 client bundle。(Next.js)
这意味着一件很重要的事：
- 不是所有服务端渲染出来的 UI 都必须水合
- 只有需要浏览器能力（事件、状态、
window、useEffect）的部分才需要成为 Client Component
从架构角度看，这让hydration从“整页动作”变成“局部动作”，你可以更精细地控制 JS 体积与主线程压力。
八、真实业务场景拆解：hydration的坑通常不是理论问题，而是链路问题
场景 1：内容站点 + 评论区
- 文章正文用
SSR输出，确保SEO与首屏可读 - 评论区用 Client Component，等用户滚动到评论区时再加载与水合
- 点赞按钮在首屏，优先水合，避免用户点击无响应
这类站点最容易踩到的坑是第三方脚本（广告、埋点）阻塞主线程，导致hydration推迟，用户误以为站点坏了。web.dev 提醒的“看起来交互但实际不能响应输入”在这种站点里非常常见。(web.dev)
场景 2：电商详情页 + 实时信息
- 商品标题、价格、主图、购买按钮：
SSR+ 优先水合 - 实时库存与倒计时：服务端输出稳定占位，客户端接管后再更新
- 推荐列表与评价瀑布流：延后水合或按需水合
这里最常见的hydration mismatch源头就是时间与随机性。Next.js 文档提供的suppressHydrationWarning适合用于那些“差异可接受但结构必须保留”的局部内容。(Next.js)
九、把hydration做好的实战准则：稳定、可控、可观测
下面这些准则，来自大量团队踩坑后的共识，背后都能对应到上面拆解的某个内部动作。
1）保证服务端与客户端首轮渲染的确定性
- 避免在 render 路径里直接用
Date.now()、Math.random() - 格式化逻辑保持一致（地区、时区、货币）
- 必须依赖浏览器信息时，用占位 + 客户端副作用更新
这样做的直接收益是减少hydration mismatch，避免框架放弃复用导致更大成本。(Next.js)
2）把交互边界缩小，别让整页都背hydration成本
- 在 Next.js 里减少
use client的蔓延范围 - 把纯展示组件留在服务端，交互组件才进客户端
这对应 Next.js 文档强调的模块图边界原则：use client会把依赖树带进 client bundle，边界越大，客户端成本越高。(Next.js)
3）对INP敏感的页面考虑渐进式或选择性水合
- 用
Suspense、按区块拆分、滚动触发等方式延后不关键区域 - 优先保证首屏关键控件可点
Vercel 在 nextjs.org 的案例说明了这种策略对TBT的潜在收益。(Vercel)
patterns.dev 对渐进式hydration的总结也在强调“拆分与延迟”是核心。(Patterns)
4）把接管期的用户交互考虑进去
- 如果页面在可见后很久才可交互，用户会提前点击
- 事件回放思路可以减少挫败感
Angular 文档对Event Replay的描述提供了一个很清晰的可参考模型：先捕获，再回放。(Angular)
十、用一句话把hydration讲到位
hydration不是给HTML贴个onClick那么简单，它是一套“在不推倒重建的前提下，让框架接管现有 DOM”的系统工程：客户端需要再渲染一遍组件树来得到期望结构，逐节点对齐并复用服务端 DOM，建立组件与节点的双向关联，接入事件系统与调度器，初始化状态并在合适时机触发副作用。React 官方对hydrateRoot的定义把它概括得很精准：把组件逻辑附着到服务端生成的HTML上，让快照变成可交互应用。(React)
而 web.dev 的提醒也同样关键：带rehydration的SSR虽然能让内容更早出现，但水合成本可能拖垮交互指标，导致页面“看起来好了却点不动”。(web.dev)
