修复 Next.js 中的水合错误

Source: Dev.to

常见的 Hydration 错误原因

浏览器/环境问题

• 浏览器扩展注入属性（密码管理器、广告拦截器、辅助功能工具）
• 浏览器自动填充向表单元素添加属性
• 第三方脚本在 React 水合之前修改 DOM
• 不同的时区导致服务器和客户端之间的日期/时间不匹配

代码问题

• 在 SSR 时使用仅浏览器可用的 API（window、localStorage、document）
• 在渲染中使用随机值或 Math.random()（服务器生成的值与客户端不同）
• 使用 new Date() 的 Date 对象而未进行统一格式化
• 使用 useEffect 或 useState 在首次渲染时修改内容
• 模板字符串中的不一致空白（额外空格、换行）
• 基于仅客户端可用的值进行条件渲染（window.innerWidth、用户代理检测）

数据问题

• 服务器和客户端获取了不同的数据或在不同时间获取
• 列表中缺少 key 属性导致重新排序问题
• 在服务器组件中使用不可序列化的数据（函数、symbol）
• 服务器和客户端之间的数据格式不一致（日期、数字、地区设置）

CSS/样式问题

• CSS‑in‑JS 库在服务器端和客户端生成不同的类名
• CSS 模块的哈希生成不一致
• 媒体查询在服务器端和客户端应用了不同的样式

组件问题

• 在行内元素内部嵌套块级元素

  <span>
    <div>inside</div>
  </span>

• 无效的 HTML 结构（SSR 可能渲染的结果与浏览器解析的结果不同）

• 第三方组件不兼容 SSR

• Portal 在不同位置渲染

最佳实践

始终检查代码是否依赖仅客户端的 API，并在需要时将其包装在 useEffect 中，或适当地使用 'use client' 指令。