Next.js中localStorage使用问题：主题切换上下文提供者报错求助

核心解决思路 #

解决你遇到的三个问题，关键要保证服务端与客户端首次渲染内容一致（避免Hydration不匹配），同时在客户端挂载后立即同步本地存储的主题，还要保证切换时无延迟：

• 服务端渲染阶段使用默认主题，避免访问window报错
• 客户端挂载后读取localStorage并更新主题，确保首次渲染与服务端一致
• 切换主题时直接同步状态、本地存储与DOM样式，实现即时切换

完整代码实现 #

1. 自定义主题Context Provider

'use client'
import { createContext, useContext, useState, useEffect, ReactNode } from 'react'

type Theme = 'light' | 'dark'

type ThemeContextType = {
  theme: Theme
  toggleTheme: () => void
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function CustomThemeProvider({ children }: { children: ReactNode }) {
  // 服务端/客户端首次渲染统一用默认主题，规避Hydration不匹配
  const [theme, setTheme] = useState<Theme>('light')

  useEffect(() => {
    // 客户端挂载后读取本地存储的主题
    const savedTheme = window.localStorage.getItem('theme') as Theme | null
    if (savedTheme) {
      setTheme(savedTheme)
      // 同步DOM类名，确保样式立即生效
      document.documentElement.classList.toggle('dark', savedTheme === 'dark')
    }
  }, [])

  const toggleTheme = () => {
    const newTheme = theme === 'light' ? 'dark' : 'light'
    setTheme(newTheme)
    // 更新本地存储
    window.localStorage.setItem('theme', newTheme)
    // 直接切换DOM类名，实现无延迟样式变更
    document.documentElement.classList.toggle('dark', newTheme === 'dark')
  }

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error('useTheme必须在CustomThemeProvider内部使用')
  }
  return context
}

2. 布局组件示例（LayoutContent）

'use client'
import { useTheme } from './CustomThemeProvider'

export default function LayoutContent({ children }: { children: ReactNode }) {
  const { theme, toggleTheme } = useTheme()

  return (
    <div className={`page-container ${theme}`}>
      <button onClick={toggleTheme} className="theme-toggle-btn">
        切换主题（当前：{theme}）
      </button>
      {children}
    </div>
  )
}

3. 配套样式（可选）

通过CSS变量实现主题样式的平滑过渡：

:root {
  --bg-color: #ffffff;
  --text-color: #111827;
}

.dark {
  --bg-color: #111827;
  --text-color: #ffffff;
}

.page-container {
  background-color: var(--bg-color);
  color: var(--text-color);
  transition: background-color 0.3s ease, color 0.3s ease;
  min-height: 100vh;
}

关键细节说明 #

• 'use client'指令：Next.js App Router环境下必须添加，确保组件仅在客户端执行，避免服务端访问window报错
• 初始默认主题：服务端渲染与客户端首次渲染使用相同的默认值，彻底解决Hydration不匹配问题
• useEffect读取本地存储：客户端挂载后立即执行，既不会触发服务端报错，又能快速同步用户之前选择的主题
• 切换逻辑直接操作DOM：更新状态的同时修改document.documentElement的类名，避免依赖React渲染周期导致的延迟

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