skillhub-088-vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
抑制预期的水合不匹配警告	低-中	抑制已知差异引起的干扰性水合警告	rendering, hydration, ssr, nextjs

抑制预期的水合不匹配警告

在 SSR 框架（如 Next.js）中，部分值在服务端与客户端存在有意差异（随机 ID、日期、区域设置/时区格式化）。对于这些预期的不匹配情况，应将动态文本包裹在带有 suppressHydrationWarning 属性的元素中，以抑制干扰性警告。切勿使用此属性掩盖真实 Bug，也不要过度使用。

错误做法（已知不匹配仍产生警告）：

function Timestamp() {
  return <span>{new Date().toLocaleString()}</span>
}

正确做法（仅抑制预期的不匹配）：

function Timestamp() {
  return (
    <span suppressHydrationWarning>
      {new Date().toLocaleString()}
    </span>
  )
}