NNext.js 中文网 GitHub

如何防止 hydration 前的闪烁

了解如何在浏览器绘制之前修正服务端渲染的 HTML(例如深色模式主题),以防止无样式内容闪烁(FOUC)。

用户偏好、浏览器设置和客户端存储在服务端渲染期间不可用。服务器会输出一个合理的默认值,但任何依赖于仅客户端状态(区域设置、时区、主题、持久化的交互)的 UI 都需要在用户看到之前更新。在浏览器绘制之后才修正它会产生无样式内容闪烁(FOUC)。

解决此问题的一些常见方法:

  • 使用客户端值重新渲染的 Client Component 会导致 hydration 错误。
  • 推迟到 useEffect 可以避免错误,但会引入可见的闪烁。
  • 仅在服务端渲染意味着完全放弃针对客户端的格式化。

使用在浏览器解析 HTML 时同步运行的内联脚本,你可以在首次绘制之前更新 DOM。本指南涵盖日期、主题和持久化的 UI 状态。

示例#

配套的演示(源码)使用 LANG=ja_JP.UTF-8 构建,以模拟服务器/客户端区域设置不匹配。它让你可以比较:

  • 使用内联脚本格式化日期,无闪烁且无 hydration 错误
  • 直接调用 toLocaleDateString() 的 Client Component,会显示 hydration 错误
  • 使用惰性 useState 初始化器将展开部分持久化到 localStorage 的手风琴组件

使用 Chrome DevTools 的 Sensors 覆盖你的区域设置(例如 ru-RU),查看每种方式的表现。

日期与格式化#

像 2026-06-15T18:00:00Z 这样的 UTC 时间戳表示一个固定的时间点,但其显示格式取决于用户的区域设置和时区。服务器上的 toLocaleDateString() 和 Intl.DateTimeFormat 使用服务器的设置,这可能与用户的设置不匹配。

问题所在#

一个自然的做法是使用格式化日期的 Client Component:

app/components/event-date.tsx
'use client'

export function EventDate({ date }: { date: string }) {
  return <p>{new Date(date).toLocaleDateString()}</p>
}
app/components/event-date.js
'use client'

export function EventDate({ date }) {
  return <p>{new Date(date).toLocaleDateString()}</p>
}

在 SSR 期间,toLocaleDateString() 在 Node.js 中运行并使用服务器的区域设置进行格式化(例如 6/15/2026)。在 hydration 时,React 在浏览器中重新执行该组件并生成用户的区域设置(例如 2026/6/15)。React 检测到不匹配,抛出 hydration 错误,用户看到闪烁。

你可以用 useEffect 在 hydration 后更新日期来规避此问题,但用户仍会先看到服务器格式化的日期。Server Component 可以完全避免该错误,但日期将永久保持服务器的区域设置格式。

小知识: 如果你的机器区域设置与浏览器的一致,这个问题在本地开发中很容易被忽略。使用与浏览器不同的 TZ 和 LANG 设置运行开发服务器,以尽早发现不匹配(例如 TZ=UTC LANG=ja_JP.UTF-8 next dev)。由于大多数服务器以 UTC 运行,TZ=UTC 是一个不错的默认值。

使用内联脚本修复#

  1. 服务器按其区域设置将日期渲染到 <p> 中。
  2. 在该元素之后放置一个 <script>(通过 dangerouslySetInnerHTML)。浏览器会在 HTML 解析期间同步运行它,且早于首次绘制。
  3. 为该元素添加 suppressHydrationWarning,因为内联脚本会在 React hydration 之前更改文本。请参阅下文的理解 suppressHydrationWarning。
app/events/page.tsx
import { getEvent } from '@/app/lib/events'

export default async function Page() {
  const event = await getEvent('nextjs-conf')

  return (
    <section>
      <h1>{event.name}</h1>
      <p id="event-date" suppressHydrationWarning>
        {new Date(event.date).toLocaleDateString()}
      </p>
      <script
        dangerouslySetInnerHTML={{
          __html: `document.getElementById("event-date").textContent=new Date("${event.date}").toLocaleDateString()`,
        }}
      />
    </section>
  )
}
app/events/page.js
import { getEvent } from '@/app/lib/events'

export default async function Page() {
  const event = await getEvent('nextjs-conf')

  return (
    <section>
      <h1>{event.name}</h1>
      <p id="event-date" suppressHydrationWarning>
        {new Date(event.date).toLocaleDateString()}
      </p>
      <script
        dangerouslySetInnerHTML={{
          __html: `document.getElementById("event-date").textContent=new Date("${event.date}").toLocaleDateString()`,
        }}
      />
    </section>
  )
}

这适用于整页加载(直接访问、刷新)。对于通过 <Link> 进行的客户端导航,请参阅提取可复用组件。

理解 suppressHydrationWarning#

当 React 进行 hydration 并发现文本不匹配时:

  • 不使用 suppressHydrationWarning 时:React 将其视为 hydration 错误,并从最近的错误或 Suspense 边界开始进行客户端渲染来恢复。这会导致闪烁,并且该边界内其他组件上的内联脚本修正会丢失,因为 React 重建 DOM 时这些脚本不会重新执行。
  • 使用 suppressHydrationWarning 时:React 保留 DOM 中的内容,并丢弃该元素的客户端输出。以 DOM 为准。

内联脚本会在 React hydration 之前将正确的值放入 DOM。即使是 Server Components,React 在 hydration 期间也会将 DOM 与 RSC payload 进行比较,而内联脚本已经更改了文本。suppressHydrationWarning 告诉 React 接受 DOM 而不是 payload。

提取可复用组件#

通过 DOM 更新插入的脚本不会在浏览器中执行。在客户端导航时,React 根据 RSC payload 渲染组件,脚本不会运行。将组件设为 Client Component 可以解决此问题:在软导航时 toLocaleDateString() 直接在浏览器中运行,而内联脚本处理硬导航。useId 为每个实例生成稳定的唯一 ID。

在开发环境中,当渲染产生 <script> 标签时 React 也会发出警告。为避免这种情况,请将脚本包装在一个辅助组件中,该组件在服务器上设置 type="text/javascript",在客户端设置 type="text/plain"。suppressHydrationWarning 会处理类型不匹配。

app/components/inline-script.tsx
export function InlineScript({ html }: { html: string }) {
  return (
    <script
      type={typeof window === 'undefined' ? 'text/javascript' : 'text/plain'}
      suppressHydrationWarning
      dangerouslySetInnerHTML={{ __html: html }}
    />
  )
}
app/components/inline-script.js
export function InlineScript({ html }) {
  return (
    <script
      type={typeof window === 'undefined' ? 'text/javascript' : 'text/plain'}
      suppressHydrationWarning
      dangerouslySetInnerHTML={{ __html: html }}
    />
  )
}

小知识: useServerInsertedHTML 也能避免该警告,但在这里它无法替代 InlineScript。它会在组件标记之前插入脚本,因此脚本会在 <time> 元素存在之前运行。它适合作用于整个文档的脚本,例如主题中的主题脚本。

app/components/local-date.tsx
'use client'

import { useId } from 'react'
import { InlineScript } from './inline-script'

export function LocalDate({
  date,
  options,
}: {
  date: string
  options?: Intl.DateTimeFormatOptions
}) {
  const id = useId()

  return (
    <>
      <time id={id} dateTime={date} suppressHydrationWarning>
        {new Date(date).toLocaleDateString(undefined, options)}
      </time>
      <InlineScript
        html={`{var n=document.getElementById("${id}");if(n)n.textContent=new Date("${date}").toLocaleDateString(undefined,${JSON.stringify(options)})}`}
      />
    </>
  )
}
app/components/local-date.js
'use client'

import { useId } from 'react'
import { InlineScript } from './inline-script'

export function LocalDate({ date, options }) {
  const id = useId()

  return (
    <>
      <time id={id} dateTime={date} suppressHydrationWarning>
        {new Date(date).toLocaleDateString(undefined, options)}
      </time>
      <InlineScript
        html={`{var n=document.getElementById("${id}");if(n)n.textContent=new Date("${date}").toLocaleDateString(undefined,${JSON.stringify(options)})}`}
      />
    </>
  )
}
  • 硬导航(初始加载、刷新):脚本在 HTML 解析期间执行并修正日期。suppressHydrationWarning 告诉 React 接受 DOM。
  • 客户端导航(通过 <Link>):toLocaleDateString() 在浏览器中作为 Client Component 渲染的一部分运行。脚本为 text/plain 并被忽略。
app/events/page.tsx
import { LocalDate } from '@/app/components/local-date'
import { getEvent } from '@/app/lib/events'

export default async function Page() {
  const event = await getEvent('nextjs-conf')

  return (
    <section>
      <h1>{event.name}</h1>
      <LocalDate
        date={event.date}
        options={{ year: 'numeric', month: 'long', day: 'numeric' }}
      />
    </section>
  )
}
app/events/page.js
import { LocalDate } from '@/app/components/local-date'
import { getEvent } from '@/app/lib/events'

export default async function Page() {
  const event = await getEvent('nextjs-conf')

  return (
    <section>
      <h1>{event.name}</h1>
      <LocalDate
        date={event.date}
        options={{ year: 'numeric', month: 'long', day: 'numeric' }}
      />
    </section>
  )
}

小知识:

  • 使用带有 dateTime 属性的 <time> 元素,以便搜索引擎和屏幕阅读器无论显示文本如何都能解析 ISO 字符串。
  • 使用 dangerouslySetInnerHTML 的内联脚本会被不允许 'unsafe-inline' 的严格内容安全策略阻止。如果你的应用使用 CSP,你需要添加一个 nonce。

主题#

你的页面可能以默认主题(例如浅色)进行服务端渲染,但用户已在 localStorage 中保存了深色模式偏好。同样的内联脚本技术也适用:读取该值并在浏览器绘制之前在 <html> 上设置 data-theme 属性。

app/layout.tsx
export default function RootLayout({ children }: LayoutProps<'/'>) {
  return (
    <html lang="en" data-theme="light" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `(function(){try{var t=localStorage.getItem("theme");if(t)document.documentElement.setAttribute("data-theme",t)}catch(e){}})()`,
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en" data-theme="light" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `(function(){try{var t=localStorage.getItem("theme");if(t)document.documentElement.setAttribute("data-theme",t)}catch(e){}})()`,
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}
app/globals.css
[data-theme='light'] {
  --background: #ffffff;
  --foreground: #000000;
}

[data-theme='dark'] {
  --background: #0a0a0a;
  --foreground: #ededed;
}

脚本在 <head> 中运行,因此正确主题会在任何内容绘制之前应用。try/catch 处理 localStorage 不可用的情况。

小知识: 你也可以在 Client Component 中从 useServerInsertedHTML 返回主题脚本,并使用 useRef 标志使其只插入一次。这样可以避免脚本警告,但脚本仅在初始文档上运行。对于主题来说这没问题,因为它在 <html> 上设置的属性会在导航之间持续存在。

与 localStorage 不同,cookie 会随每个请求一起发送,因此服务器可以通过 cookies() 读取它。但在根布局中读取它会让整个应用退出静态预渲染(并且在 Cache Components 下,会强制阻塞该布局下的每个路由段)。要让页面保持使用通用默认值进行静态预渲染,同时避免闪烁,请改为在内联脚本中读取 cookie:

app/layout.tsx
export default function RootLayout({ children }: LayoutProps<'/'>) {
  return (
    <html lang="en" data-theme="light" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `(function(){try{var m=document.cookie.match(/(?:^|; )theme=([^;]*)/);if(m)document.documentElement.setAttribute("data-theme",decodeURIComponent(m[1]))}catch(e){}})()`,
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en" data-theme="light" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `(function(){try{var m=document.cookie.match(/(?:^|; )theme=([^;]*)/);if(m)document.documentElement.setAttribute("data-theme",decodeURIComponent(m[1]))}catch(e){}})()`,
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}

要切换主题,请在 <html> 上设置属性并将选择持久化到 cookie:

js
const theme = 'dark'
document.documentElement.setAttribute('data-theme', theme)
document.cookie = `theme=${encodeURIComponent(theme)}; path=/; max-age=31536000; SameSite=Lax`

与 React state 同步#

当 Client Component 管理交互状态(例如手风琴的哪个部分展开)时,React 的初始状态必须与内联脚本设置的 DOM 相匹配。使用惰性状态初始化器,从与脚本相同的来源读取。

app/components/accordion.tsx
'use client'

import { useState, useCallback } from 'react'
import { InlineScript } from './inline-script'

const STORAGE_KEY = 'open-section'

const sections = [
  {
    id: 'setup',
    title: 'Setup',
    content: 'Install dependencies and create your project.',
  },
  {
    id: 'usage',
    title: 'Usage',
    content: 'Import the component and pass your data.',
  },
  {
    id: 'deploy',
    title: 'Deploy',
    content: 'Push to your Git provider and deploy.',
  },
]

const DEFAULT_ID = sections[0].id
const SECTION_IDS = sections.map((s) => s.id)

export function Accordion() {
  const [openId, setOpenId] = useState(() => {
    if (typeof window === 'undefined') return DEFAULT_ID
    return localStorage.getItem(STORAGE_KEY) ?? DEFAULT_ID
  })

  const handleToggle = useCallback(
    (id: string) => (e: React.ToggleEvent<HTMLDetailsElement>) => {
      if (e.newState === 'open') {
        setOpenId(id)
        localStorage.setItem(STORAGE_KEY, id)
      }
    },
    []
  )

  return (
    <div>
      {sections.map((section) => (
        <details
          key={section.id}
          name="accordion"
          id={`section-${section.id}`}
          open={openId === section.id}
          onToggle={handleToggle(section.id)}
        >
          <summary>{section.title}</summary>
          <p>{section.content}</p>
        </details>
      ))}
      <InlineScript
        html={`{var id=localStorage.getItem("${STORAGE_KEY}")??"${DEFAULT_ID}";${JSON.stringify(SECTION_IDS)}.forEach(function(s){var el=document.getElementById("section-"+s);if(el){if(s===id)el.setAttribute("open","");else el.removeAttribute("open")}})}`}
      />
    </div>
  )
}
app/components/accordion.js
'use client'

import { useState, useCallback } from 'react'
import { InlineScript } from './inline-script'

const STORAGE_KEY = 'open-section'

const sections = [
  {
    id: 'setup',
    title: 'Setup',
    content: 'Install dependencies and create your project.',
  },
  {
    id: 'usage',
    title: 'Usage',
    content: 'Import the component and pass your data.',
  },
  {
    id: 'deploy',
    title: 'Deploy',
    content: 'Push to your Git provider and deploy.',
  },
]

const DEFAULT_ID = sections[0].id
const SECTION_IDS = sections.map((s) => s.id)

export function Accordion() {
  const [openId, setOpenId] = useState(() => {
    if (typeof window === 'undefined') return DEFAULT_ID
    return localStorage.getItem(STORAGE_KEY) ?? DEFAULT_ID
  })

  const handleToggle = useCallback(
    (id) => (e) => {
      if (e.newState === 'open') {
        setOpenId(id)
        localStorage.setItem(STORAGE_KEY, id)
      }
    },
    []
  )

  return (
    <div>
      {sections.map((section) => (
        <details
          key={section.id}
          name="accordion"
          id={`section-${section.id}`}
          open={openId === section.id}
          onToggle={handleToggle(section.id)}
        >
          <summary>{section.title}</summary>
          <p>{section.content}</p>
        </details>
      ))}
      <InlineScript
        html={`{var id=localStorage.getItem("${STORAGE_KEY}")??"${DEFAULT_ID}";${JSON.stringify(SECTION_IDS)}.forEach(function(s){var el=document.getElementById("section-"+s);if(el){if(s===id)el.setAttribute("open","");else el.removeAttribute("open")}})}`}
      />
    </div>
  )
}

内联脚本和惰性 useState 初始化器都从 localStorage 读取。它们始终一致,因此 React 的初始状态与 DOM 相匹配。

在开发中重新应用属性#

内联脚本在解析期间设置属性,这正是生产构建所需的全部。但在开发中,React 的 Strict Mode 会重新挂载组件一次以暴露错误,并在重新挂载时将 <html>、<head> 和 <body> 重置为仅保留它从 JSX 管理的属性,从而清除脚本设置的属性。随后页面在渲染时就没有了该属性,忽略了该值的真实来源。

解决此问题的一种方法是做一些在没有内联脚本时你会做的事情。在拥有主题的组件中,在绘制之前运行的 useLayoutEffect 中,从客户端读取存储的值并应用它:

app/components/theme-toggle.tsx
'use client'

import { useLayoutEffect } from 'react'

export function ThemeToggle() {
  // 在 React 于开发模式重新挂载时清除该属性后重新应用。在生产环境中这是空操作。
  useLayoutEffect(() => {
    const theme = localStorage.getItem('theme')
    if (theme) document.documentElement.setAttribute('data-theme', theme)
  }, [])

  function toggle() {
    const next =
      (localStorage.getItem('theme') ?? 'light') === 'dark' ? 'light' : 'dark'
    localStorage.setItem('theme', next)
    document.documentElement.setAttribute('data-theme', next)
  }

  return <button onClick={toggle}>Toggle theme</button>
}

何时使用其他方法#

情况方法
日期依赖于请求数据(cookie、标头)使用 headers() 或 cookies() 读取请求数据并在服务端格式化
日期实时更新(倒计时、时钟)使用带有 useEffect 和 suppressHydrationWarning 的 Client Component
页面已经完全动态使用 Accept-Language 标头在服务端格式化日期
在不同语言之间翻译内容使用国际化配合按区域设置的静态构建或动态渲染

为什么不用 useEffect?#

useEffect 在 hydration 和绘制之后运行。用户先看到服务器的值,然后是修正后的值。在 effect 中设置状态还会触发重新渲染,这可能会重新激活父级 Suspense 边界。

useLayoutEffect 在绘制之前但在 hydration 之后运行。它可以防止 hydration 与绘制之间的闪烁,但无法防止 HTML 到达与 React hydration 之间的闪烁。在慢速连接上,浏览器会在 React 加载之前绘制服务器 HTML。内联脚本在 HTML 解析期间运行,早于 React 介入。

使用 await headers() 读取 Accept-Language 使服务器能够按请求进行格式化。借助 Cache Components,你可以只将日期部分包裹在 Suspense fallback 中,使页面其余部分保持静态。但你需要显示 fallback 而不是即时内容,而且 Accept-Language 不包含时区信息。

下一步#

Next.js 中文网