Next.js服务端组件中替代useState实现默认暗黑模式交互

核心思路 #

将根布局保留为服务端组件，默认渲染暗黑模式的DOM结构；把暗黑模式切换按钮拆分为独立的客户端组件，通过hydration实现交互，同时处理用户偏好的持久化与服务端/客户端状态同步，避免 hydration 不匹配和页面闪烁。

步骤1：改造RootLayout为服务端组件 #

移除"use client"指令，直接在服务端渲染默认暗黑模式的HTML结构，保证首次加载即显示暗黑主题：

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // 优先读取用户cookie中的主题偏好，无则默认启用暗黑模式
  const cookieStore = cookies();
  const savedTheme = cookieStore.get('theme')?.value;
  const isDarkMode = savedTheme ? savedTheme === 'dark' : true;

  return (
    <html lang="en" className={isDarkMode ? 'dark' : ''}>
      <body className="min-h-screen">
        <nav className="p-4">
          {/* 引入客户端组件实现切换交互 */}
          <ThemeToggle initialTheme={isDarkMode} />
        </nav>
        <main className="container mx-auto p-4">
          {children}
        </main>
      </body>
    </html>
  );
}

步骤2：创建独立的客户端切换组件 #

单独编写ThemeToggle.tsx，仅对该组件进行hydration，不影响整个布局的服务端渲染性能：

// app/ThemeToggle.tsx
'use client';

import { useState, useEffect } from 'react';

type ThemeToggleProps = {
  initialTheme: boolean;
};

export default function ThemeToggle({ initialTheme }: ThemeToggleProps) {
  // 初始状态与服务端渲染的主题保持一致，避免hydration不匹配
  const [isDarkMode, setIsDarkMode] = useState(initialTheme);

  useEffect(() => {
    // 同步DOM类名与当前状态
    document.documentElement.classList.toggle('dark', isDarkMode);
    // 持久化到localStorage和cookie，服务端下次请求可读取cookie
    localStorage.setItem('theme', isDarkMode ? 'dark' : 'light');
    document.cookie = `theme=${isDarkMode ? 'dark' : 'light'}; path=/; max-age=31536000`;
  }, [isDarkMode]);

  const handleToggle = () => {
    setIsDarkMode(prev => !prev);
  };

  return (
    <button
      onClick={handleToggle}
      aria-label={isDarkMode ? '切换到浅色模式' : '切换到深色模式'}
      className="p-2 rounded-full hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors"
    >
      {isDarkMode ? '🌞' : '🌙'}
    </button>
  );
}

关键细节说明 #

1. 避免Hydration Mismatch：客户端组件的初始状态直接使用服务端传递的initialTheme，确保首次渲染的DOM与服务端输出完全一致，不会触发React的不匹配警告。
2. 无闪烁体验：服务端直接渲染暗黑模式的类名，无需等待客户端JS加载完成再切换主题，彻底消除页面闪烁。
3. 偏好持久化：同时使用localStorage（客户端快速读取）和cookie（服务端请求时读取），保证用户刷新页面或重新访问时，主题偏好能无缝延续。
4. 性能优化：仅对切换按钮这一小部分进行客户端hydration，根布局仍保持服务端渲染的性能优势。

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