Next.js Hydration Error文本不匹配服务端渲染HTML的原因与解决方法

Next.js 采用服务端渲染（SSR）/静态站点生成（SSG）能力时，页面首次返回给浏览器的HTML内容完全由服务端计算生成。浏览器加载HTML后，React会执行水合流程：在客户端重新渲染一遍页面组件，将生成的DOM树和服务端返回的现有DOM做逐节点比对，只有两边结构、文本内容完全一致时，才能顺利绑定事件监听器，完成页面的交互激活。
当组件渲染逻辑依赖localStorage这类仅客户端存在的存储数据时：

• 服务端执行渲染逻辑时无window对象，示例中的getTempUserShortId函数会直接返回空字符串，最终渲染到HTML里的对应位置内容为空
• 客户端首次执行渲染逻辑时可正常访问window，会从localStorage读取已存ID、或生成新的随机ID返回，渲染出的文本是实际的临时用户ID
  两边渲染出的文本内容不一致，就会触发水合报错：

Error: Text content does not match server-rendered HTML.

• 方案1：挂载后再读取客户端专属数据（优先推荐）
  水合流程仅校验组件首次渲染的输出结果，useEffect钩子会在水合全部完成后才执行，不会参与水合阶段的内容比对。你可以将初始状态设置为和服务端输出一致的值，等组件挂载后再读取localStorage更新状态，从根源避免内容 mismatch。
  示例代码：

  // App Router下需标记为客户端组件，Pages Router无需此行
  'use client'
  import { useState, useEffect } from 'react'
  
  function TempUserDisplay() {
    // 初始值和服务端返回保持一致，保证水合阶段两边内容完全相同
    const [tempId, setTempId] = useState('')
  
    useEffect(() => {
      // 水合完成后执行，此时操作localStorage、更新状态都不会触发水合错误
      let storedId = localStorage.getItem('tempUserShortId')
      if (!storedId) {
        storedId = randomString(4)
        localStorage.setItem('tempUserShortId', storedId)
      }
      setTempId(storedId)
    }, [])
  
    return <div>当前临时用户ID：{tempId}</div>
  }
  

  如果需要优化体验，可以在tempId为空时返回骨架屏、loading占位，等ID读取完成后再展示真实内容。

• 方案2：动态导入关闭组件SSR
  如果某块组件的逻辑完全依赖客户端API，不需要服务端参与渲染，可以使用Next.js内置的动态导入能力，直接关闭该组件的服务端渲染，组件只会在客户端完成渲染，自然不会存在服务端和客户端内容不一致的问题。
  示例代码：

  // 单独封装客户端专属组件，例如 components/temp-user.jsx
  'use client'
  const getTempUserShortId = () => {
    let tempUserShortId = localStorage.getItem('tempUserShortId')
    if (tempUserShortId === null) {
      tempUserShortId = randomString(4)
      localStorage.setItem('tempUserShortId', tempUserShortId)
    }
    return tempUserShortId
  }
  
  export default function TempUser() {
    const id = getTempUserShortId()
    return <div>当前临时用户ID：{id}</div>
  }
  
  // 在需要引入该组件的页面/父组件中，使用动态导入关闭SSR
  import dynamic from 'next/dynamic'
  const TempUser = dynamic(() => import('@/components/temp-user'), {
    ssr: false,
    // 可选：加loading占位提升体验
    loading: () => <div>加载中...</div>
  })
  

• 方案3：节点级跳过水合校验（仅适合极简单场景）
  如果只是单个节点存在固定的客户端/服务端内容差异，且差异不影响核心功能，可以给对应DOM节点添加suppressHydrationWarning={true}属性，React会跳过该节点的一级内容水合校验。这个方案的适用范围非常窄，不要大范围使用，否则会掩盖真实存在的水合逻辑问题。

注意：不要通过在服务端全局伪造window、localStorage对象的方式强行对齐渲染内容，这类hack不仅无法匹配不同用户本地存储的真实值，还可能引发内存泄漏、数据串扰等服务端渲染问题。

内容的提问来源于stack exchange，提问作者János