NextJS 13 App Router主题切换与React服务端组件兼容方案咨询

核心思路是将所有依赖浏览器API的主题控制逻辑抽离到独立的客户端组件中，根布局保持为服务器组件，仅负责渲染该客户端组件及其他服务器端内容，这样既不影响子路由的SSR能力，又能实现完整的主题切换功能。

步骤1：修复Zustand Store的服务器端兼容性问题 #

原Store的初始状态直接依赖window对象，服务器端渲染时会报错，需调整初始化逻辑：

// store/zustand/themeStore.ts
import { createJSONStorage, persist } from 'zustand/middleware'
import { createZustandChildrenStore } from './store'

export enum Theme {
  light = 'light',
  dark = 'dark',
}

type State = {
  theme: Theme
}

type Actions = {
  setCurrentTheme: (theme: Theme) => void
  isLightTheme: () => boolean
  reset: () => void
}

type ThemeStore = State & Actions

// 服务器端使用默认light主题，客户端再根据系统偏好或localStorage修正
const initialState: State = {
  theme: Theme.light,
}

const useThemeStore = createZustandChildrenStore<ThemeStore>()(
  persist(
    (set, get) => ({
      ...initialState,
      setCurrentTheme: (theme: Theme) => {
        set({ theme })
      },
      isLightTheme: () => {
        return get().theme === Theme.light
      },
      reset: () => set(initialState),
    }),
    {
      name: 'themeStorage',
      storage: createJSONStorage(() => localStorage),
    }
  )
)

export { useThemeStore }
export type { ThemeStore }

步骤2：创建独立的客户端主题控制组件 #

新建components/ThemeProvider.tsx，将所有浏览器相关逻辑移至此处：

// components/ThemeProvider.tsx
'use client'

import { Theme, useThemeStore } from '@/store/zustand/themeStore'
import { dark } from '@clerk/themes'
import { useEffect } from 'react'
import { useClerk } from '@clerk/nextjs'

export default function ThemeProvider({ children }: { children: React.ReactNode }) {
  const { theme, setCurrentTheme, isLightTheme } = useThemeStore()
  const { appearance } = useClerk()

  // 初始化主题：优先localStorage，其次系统偏好
  useEffect(() => {
    const savedTheme = localStorage.getItem('themeStorage')
    if (!savedTheme) {
      const isDarkPreferred = window.matchMedia('(prefers-color-scheme: dark)').matches
      setCurrentTheme(isDarkPreferred ? Theme.dark : Theme.light)
    }

    // 监听系统主题变化
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
    const handleThemeChange = (event: MediaQueryListEvent) => {
      setCurrentTheme(event.matches ? Theme.dark : Theme.light)
    }
    mediaQuery.addEventListener('change', handleThemeChange)

    return () => mediaQuery.removeEventListener('change', handleThemeChange)
  }, [setCurrentTheme])

  // 同步主题到HTML标签和Clerk
  useEffect(() => {
    document.querySelector('html')?.setAttribute('data-theme', theme)
    // 更新Clerk主题
    appearance.set({ baseTheme: isLightTheme() ? undefined : dark })
  }, [theme, isLightTheme, appearance])

  return <>{children}</>
}

步骤3：修改根布局为服务器组件 #

移除原布局中的客户端逻辑，仅保留服务器端可执行的代码，并引入上述ThemeProvider：

// app/layout.tsx
import { inter } from '@/font'
import { ClerkProvider } from '@clerk/nextjs'
import ThemeProvider from '@/components/ThemeProvider'
import '../globals.css'

export const metadata = {
  title: 'Goater',
  description: "Vote for the Goat"
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <ClerkProvider>
      <html lang="en" className={inter.className}>
        <body>
          {/* 客户端主题控制组件，不影响其他内容的SSR */}
          <ThemeProvider>
            {children}
          </ThemeProvider>
        </body>
      </html>
    </ClerkProvider>
  )
}

额外优化：解决SSR样式闪烁问题 #

为避免页面初始渲染时出现主题闪烁（服务器渲染light主题，客户端切换为dark），可在根布局中通过读取cookie获取用户主题偏好（需提前将主题同步到cookie），在服务器端直接设置data-theme：

1. 在ThemeProvider的useEffect中，同步主题到cookie：

// ThemeProvider.tsx 中的同步主题useEffect
useEffect(() => {
  document.querySelector('html')?.setAttribute('data-theme', theme)
  appearance.set({ baseTheme: isLightTheme() ? undefined : dark })
  // 同步到cookie，有效期365天
  document.cookie = `theme=${theme}; path=/; max-age=31536000`
}, [theme, isLightTheme, appearance])

2. 在根布局中读取cookie并设置data-theme：

// app/layout.tsx
import { cookies } from 'next/headers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const cookieStore = cookies()
  const savedTheme = cookieStore.get('theme')?.value || 'light'

  return (
    <ClerkProvider>
      <html lang="en" className={inter.className} data-theme={savedTheme}>
        <body>
          <ThemeProvider>
            {children}
          </ThemeProvider>
        </body>
      </html>
    </ClerkProvider>
  )
}

这样服务器端会直接渲染用户偏好的主题，彻底消除闪烁问题。

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