You need to enable JavaScript to run this app. Next.js无额外依赖实现暗黑模式:基于useState/useEffect切换body类名
优惠活动
大模型
产品
解决方案
定价
更多

Next.js无额外依赖实现暗黑模式:基于useState/useEffect切换body类名

零依赖、不碰Custom Document的纯组件内暗黑模式实现

你现在的卡点本质是把服务端渲染的环境限制和客户端交互逻辑混在一起了,其实只要严格把客户端专属的DOM操作放到useEffect里,完全可以靠现有组件内的状态实现body类的双向切换,不需要额外改全局配置:

1. 合并冗余状态,统一数据源

之前你拆分了click(控制图标显示)、dark(控制主题)两个独立状态,非常容易出现图标和实际主题不同步的问题,直接把dark作为整个主题逻辑的唯一状态源,删掉多余的click状态:

// Next.js App Router 下,带交互的客户端组件必须加这个标记
'use client'
import { useState, useEffect } from 'react'
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faSun, faMoon } from '@fortawesome/free-solid-svg-icons'

export default function Navbar() {
  // 初始值设为undefined,用来标记客户端水合完成的节点,避免SSR渲染结果和客户端不一致报错
  const [dark, setDark] = useState(undefined)

  // 切换逻辑直接基于dark状态取反,不需要单独的click计数
  const toggleDarkMode = () => {
    setDark(prev => !prev)
  }

  // 图标渲染逻辑:
  // dark为true(当前处于暗黑模式)时显示太阳图标(点击切回亮模式)
  // 初始dark为undefined时,先渲染月亮图标,和服务端的默认渲染结果对齐,避免水合错误
  const displayIcon = dark ? faSun : faMoon

2. 用useEffect处理所有DOM操作

所有涉及document、window的调用都是客户端专属的,放在useEffect中执行完全不会触发SSR报错,也不需要引入Custom Document做服务端的类名注入:

useEffect(() => {
    // 首次挂载阶段:客户端环境下初始化真实主题
    if (dark === undefined) {
      // 优先读取用户之前保存在本地的主题选择
      const savedTheme = localStorage.getItem('site-current-theme')
      if (savedTheme) {
        setDark(savedTheme === 'dark')
        return
      }
      // 没有本地存储记录时,自动匹配系统的明暗偏好
      const systemPreferDark = window.matchMedia('(prefers-color-scheme: dark)').matches
      setDark(systemPreferDark)
      return
    }

    // 主题值稳定后,直接同步修改body的className,实现light/dark双向切换
    const bodyElement = document.body
    if (dark) {
      bodyElement.classList.remove('light')
      bodyElement.classList.add('dark')
      // 把当前主题存到本地,下次访问直接读取
      localStorage.setItem('site-current-theme', 'dark')
    } else {
      bodyElement.classList.remove('dark')
      bodyElement.classList.add('light')
      localStorage.setItem('site-current-theme', 'light')
    }
  }, [dark]) // 依赖dark状态,每次状态变化自动同步body类名

3. 替换原有渲染逻辑

把之前的图标和点击事件绑定到统一的dark状态上就行:

return (
    <nav>
      {/* 其他导航栏内容 */}
      <FontAwesomeIcon
        onClick={toggleDarkMode}
        icon={displayIcon}
        className="icon"
      />
    </nav>
  )
}

实现要点说明

  • 不用Custom Document也完全可以:Custom Document是服务端渲染阶段的全局配置,我们现在的所有类名修改都是在客户端水合完成后通过DOM API操作的,和Custom Document的逻辑完全不冲突,也不需要在那个层级绑定点击事件。
  • 初始值设为undefined的作用:规避SSR水合不匹配的问题——服务端没有localStorage、window这些API,如果你一开始就把dark设为确定的布尔值,客户端第一次渲染时读出来的用户偏好和服务端渲染的默认值对不上,就会触发React的 hydration 报错。用undefined做初始标记,第一次useEffect执行时才把真实的主题值同步到状态中,整个过程和服务端的渲染结果完全对齐。
  • 完全没有引入第三方依赖:所有用到的API都是浏览器原生提供的,不需要额外安装主题管理类的包。

内容的提问来源于stack exchange,提问作者Eyad Farah

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.26 13:36:00