NextJS中Zustand持久化状态引发水合错误的解决方法

触发Hydration报错的核心逻辑：Zustand官方persist中间件默认依赖浏览器端localStorage存储持久化数据，服务端渲染阶段无法访问浏览器存储，只能返回代码里写的初始默认值；客户端首次hydration时会直接读取本地存储的持久化值更新UI，导致服务端输出的DOM和客户端首次渲染的DOM结构不匹配，直接抛出渲染错误。

核心思路：服务端渲染阶段统一使用初始默认值，等客户端完成挂载、persist完成本地存储状态同步后，再渲染依赖持久化状态的业务内容，从根源上避免两端DOM不一致。

1. 改造Zustand Store，增加水合状态标记 #

给store增加水合完成的标识位，同时配置persist中间件不持久化该标识位：

// store/useAppStore.js
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'

const useAppStore = create(
  persist(
    (set) => ({
      // 业务状态
      theme: 'light', // 默认主题
      user: null, // 默认用户信息
      // 水合状态标记，初始为false
      hasHydrated: false,
      // 状态修改方法
      setTheme: (theme) => set({ theme }),
      setUser: (user) => set({ user }),
      setHasHydrated: (status) => set({ hasHydrated: status }),
    }),
    {
      name: 'app-storage', // localStorage存储的key名
      storage: createJSONStorage(() => localStorage),
      // 配置只持久化业务状态，不存水合标记
      partialize: (state) => ({
        theme: state.theme,
        user: state.user,
      }),
    }
  )
)

export default useAppStore

2. 新增客户端Store容器组件，统一处理水合逻辑 #

在客户端组件中通过useEffect监听挂载状态，挂载完成后手动触发persist的状态同步，同步完成前返回与服务端渲染一致的占位内容：

// app/StoreHydration.js
'use client'
import { useEffect, useState } from 'react'
import useAppStore from '@/store/useAppStore'

export default function StoreHydration({ children }) {
  const [mounted, setMounted] = useState(false)
  const setHasHydrated = useAppStore(state => state.setHasHydrated)

  useEffect(() => {
    // 触发persist从localStorage同步状态
    useAppStore.persist.rehydrate()
    // 标记水合完成
    setHasHydrated(true)
    setMounted(true)
  }, [setHasHydrated])

  // 未完成挂载/水合时，返回与服务端初始渲染一致的占位
  // 注意占位样式要和默认主题匹配，避免首屏闪烁
  if (!mounted) {
    return <div className="min-h-screen bg-white"></div>
  }

  return <>{children}</>
}

3. 在根布局中接入水合组件 #

Next.js App Router在app/layout.js中引入组件包裹所有路由内容，Pages Router可在pages/_app.js中接入：

// app/layout.js
import StoreHydration from './StoreHydration'

export const metadata = {
  title: 'Next Firebase Starter',
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <StoreHydration>
          {children}
        </StoreHydration>
      </body>
    </html>
  )
}

4. （可选）优化首屏主题闪烁 #

如果需要避免水合完成前主题样式闪烁，可以在根布局的head中加入一段内联同步脚本，在页面资源加载前就读取本地存储的主题值，提前给html根标签加对应样式类：

// app/layout.js 新增head内脚本
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              try {
                const storageData = localStorage.getItem('app-storage')
                if (storageData) {
                  const parsed = JSON.parse(storageData)
                  const savedTheme = parsed?.state?.theme
                  if (savedTheme === 'dark') {
                    document.documentElement.classList.add('dark')
                  }
                }
              } catch (err) {
                // 读取失败时默认使用初始浅色主题，不做处理
              }
            `
          }}
        />
      </head>
      <body>
        <StoreHydration>
          {children}
        </StoreHydration>
      </body>
    </html>
  )
}

• 所有依赖持久化状态（主题、用户登录信息等）的组件，必须在水合完成后再读取对应状态，避免渲染不一致
• 不要在服务端组件中直接读取带persist配置的Zustand store，服务端无法访问浏览器存储，必然会出现状态不匹配
• 水合完成前的占位内容样式需要和初始默认主题保持一致，避免出现明显的样式跳变

内容的提问来源于stack exchange，提问作者Salman Fazal