在 Next.js 开发中，你大概率会遇到一个词：水合。很多同学第一次听到这个词会一脸懵：水合？是化学反应吗，跟渲染有什么关系？

其实说白了水合就是让服务端渲染出来的“静态 HTML”活过来的过程。这篇文章用最直白的语言，带你彻底搞懂水合的原理、流程、坑点和常用方法。

使用者痛点：页面已经渲染出来却点不到按钮、输入框无法输入，感觉页面“卡死”。怎么说呢，

想象一下这个场景：

你在餐厅点了一份水饺。服务员端上来一盘已经煮熟的饺子。饺子看起来完整、能吃，但如果你要蘸醋、加辣椒油，得自己动手。水合就是你自己调蘸料、动筷子的过程——让静态的饺子变成一顿可以“交互”的饭。

对应到 React：

• 服务端渲染服务器把组件跑一遍，生成完整的 HTML 字符串发给浏览器。此时页面有内容但无交互就像煮熟的饺子，能吃但没蘸料。
• 水合浏览器下载并执行 JS 后React 在客户端接管这个静态 HTML，给每个元素绑定事件监听器、恢复组件状态。于是按钮能点了输入框能打字了页面“活”了。

一句话概括：水合是 React 将事件监听器和内部状态附加到服务端渲染的静态 HTML 上的过程。

二、为什么需要水合？

使用者痛点：SSR 页面首屏快。却发现所有交互都失效，需要额外手动写大量 client‑side 代码才能修复。

You might ask: SSR already returns complete HTML,*** run JS again?按理说，Because HTML is just a “snapshot” of UI。it has no interactivity.

服务端渲染的 HTML 长这样：

点击我

但这个按钮在浏览器里是“死”的，点击没反应。话说回来，因为没有任何 JS 给它绑定 onClick 事件。要让按钮能响应点击，必须执行客户端 JS；其实，React 会创建一个虚拟 DOM 树，与服务器生成的真实 DOM 对比。接下来把事件监听器“贴”上去，这个过程就是水合。

No hydration → SSR page is just a pretty static screenshot,not a usable app.

三、水合的具体流程

以下示例为 Next.js 中一个最简单的客户端组件：

'use client';import { useState } from 'react';export default function Counter {
const = useState;return (
 setCount}>
点击次数这方面，{count}

);}

. 服务端渲染

The server runs component once and streams out plain HTML:

点击次数：

• The onClick) attribute does NOT appear because event listeners cannot be serialized.
• The initial state is rendered into markup.

. 客户端加载 JS

The browser receives HTML and in parallel starts downloading JavaScript bundle that contains React runtime and component code.

. 水合

The downloaded script runs:

1. Create a virtual DOM tree by executing component function again.
2. If virtual tree matches existing real DOM,React:
• Keeps server‑generated nodes .
• Patches event listeners ) onto those nodes.
• Takes over component state so future updates work.
3. If y differ。React throws a hydration warning/error.

. 交互阶段

User clicks → triggers onClick) → setCount updates state → React re‑renders only changed parts.

关键点：

四、水合与 CSR 的区别

渲染方式	客户端初始 DOM	React 在客户端的动作
C​SR	A empty #root	Create entire DOM from scratch.
S​SR + Hydration	The full HTML generated by server.

C​SR 就像给你一袋面粉和馅料，让你自己包、自己煮;水合则是餐厅已经把饺子煮好，你只需要蘸醋吃**。

C​SR 更慢，因为必须等全部 JS 下载完才能开始呈现；而水合利用服务器已生成好的首屏内容，加速了感知加载时间。 老实说，**

五、水合失败：最常见的坑

The rule is strict: The server‑rendered HTML must match exactly what React renders on client during its first pass.If y diverge。you’ll see warnings or broken UI.

典型错误示例

'use client';export default function BadComponent {
return (

至于当前时间，{new Date.toLocaleTimeString}

);}

• The server renders one timestamp;话说回来，client renders anor → mismatch.
• This triggers:

  Hydration failed because initial UI does not match what was rendered on server.

• You’ll also see flickering or duplicated content.

方法

1. If you need dynamic data。move it into useEffect . The effect runs **after** hydration.

   'use client';import { useEffect,useState } from 'react';export default function GoodComponent {
   const = useState;useEffect => {
   setTime.toLocaleTimeString);},)，return 
   
   当前时间的观点是，{time}
   }

Avoid using suppressHydrationWarning={true};it merely hides symptoms without fixing root cause.

常见导致 Hydration Mismatch 的因素

• 使用 Math.random Date.now等非确定性值。
• 直接访问 window 、 localStorage 等只能在浏览器运行时获得的数据。
• 依赖于时区、语言或浏览器特性的差异。
• 服务器与客户端依赖版本不一致导致输出不同。

六、Next.js 中的水合策略

• App Router 为水 合提供了多项调整，让首屏交互更快、更可靠。

. 服务端组件不参与水 合

• 只有标记了 `'use client'` 的组件才会被 hydrate。
• 服务端组件永远 **不会** 被 water​ate，也没有事件监听器。
• 它们输出后就是最终静态内容，可直接缓存。

. 选择性水 合

• React 可以优先 water​ate 使用者当前正在交互的区域，而延迟其他区域。
• 例如 Header 与 Sidebar 同时存在时如果使用者先点击 Header。则 Header 会先完成 water​ation，使感知可交互时间大幅下降。

. 流式 SSR 与 水 合

• Next.js 支持流式渲染，将 HTML 分块发送到浏览 器。
• 浏览 器在收到第一块后立即开始绘制。同时后台继续下载 JavaScript 包，实现 “边加载边 water​ate”。

七、"

• 概念：Water​ation 是 React 把事件监听器和状态附加到服务端生成的静态 HTML 上 的过程。话说回来，
• 流程：SSR ➜ 浏览 器下载 JS ➜ 对比虚拟 DOM ➜ 附加事件 ➜ 页面可交互。说起来，
• 与 CSR 区别：Water​ation 是复用已有 DOM。CSR 是从零创建 DOM。说起来，
• 最大坑：服务器和客户端第一次渲染结果必须保持一致。否则会出现 hydration mismatch 错误。
• Next.js 调整：选择性 water​ation 、流式 SSR 等，让 TTI 更快、更稳定。

---