Next.js Hydration failed 报错怎么解决？5 个常见原因和修复（SSR 不匹配）

Next.js 报 Hydration failed because the initial UI does not match what was rendered on the server 或 Text content does not match server-rendered HTML，核心只有一句话：服务端渲染（SSR）生成的 HTML，和客户端 React 接管（hydration）时算出来的不一样。

React 期望两边完全一致，对不上就报错。下面是 5 个最常见的"两边不一致"来源。

① 渲染里用了每次都变的值（Date / Math.random）

成因：服务端渲染时和客户端 hydration 时分别算了一次 new Date()、Math.random()、Date.now()，两次结果不同，HTML 自然对不上。

修复：把这类值放进 useEffect（只在客户端算一次），或用固定的初始值：

const [time, setTime] = useState(null);
useEffect(() => { setTime(new Date().toLocaleString()); }, []);
return <span>{time ?? ""}</span>;   // 首屏服务端渲染空,客户端再填

② 直接用了 typeof window / localStorage 决定渲染

成因：typeof window !== "undefined" ? A : B 这种写法，服务端走 B、客户端走 A，两边渲染不同。

修复：初次渲染保持和服务端一致（当作没有 window），等 useEffect 后再读 localStorage / window 更新状态。

③ 非法的 HTML 嵌套

成因：<p> 里塞 <div>、<a> 套 <a>、<table> 结构不合法等，浏览器会自动"纠正"DOM，于是和服务端 HTML 不一致。

修复：检查报错指向的组件，把非法嵌套改成合法结构（<p> 里只放行内元素，块级元素用 <div>）。

④ 第三方组件 / 库只能在客户端跑

成因：图表、地图、富文本等依赖 window 的库，在 SSR 阶段渲染就不一致或直接报 window is not defined。

修复：动态导入并关掉 SSR：

import dynamic from "next/dynamic";
const Chart = dynamic(() => import("./Chart"), { ssr: false });

⑤ 浏览器扩展或本地化改了 DOM

成因：有些浏览器扩展（翻译、暗色模式、密码管理器）会在 hydration 前改 DOM，导致不匹配。这类不是你代码的 bug。

修复：先用无扩展的隐身窗口确认是不是扩展导致；如果是你有意的客户端差异（如时间、主题），在该元素上加 suppressHydrationWarning：

<time suppressHydrationWarning>{clientTime}</time>

suppressHydrationWarning 只压制单个元素的警告，别全局滥用。

怎么定位是哪一段

React 的报错通常会指出不匹配的文本或元素。对照它检查：这段内容是不是依赖了时间、随机数、window、localStorage，或有没有非法嵌套。把可疑组件先 ssr: false 动态导入，能排掉就锁定了。

让 Codex 辅助

我的 Next.js 报 Hydration failed（贴完整报错和它指出的组件/文本）。
请判断最可能是哪类不匹配（时间随机值 / window / 非法嵌套 / 仅客户端库），
给出对应修复方向，先不要直接改我的组件代码。

风险提醒

• 别用 suppressHydrationWarning 或随手 ssr: false 把所有警告压掉——那是盖住问题，可能影响 SEO（内容首屏不渲染）。
• 改渲染逻辑前先有 Git 记录，方便对比前后行为。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关报错排查

同一套排查思路的常见报错，建议一起看：

• npm run dev 能跑但 build 失败
• Cannot find module 报错怎么解决
• .env 环境变量不生效怎么解决

免责声明

本文成因与修复对应 React / Next.js 的 SSR 与 hydration 通用行为，供学习和排查参考；具体项目涉及客户代码时需明确授权并人工复核。