Next 13 + Tailwind 暗黑模式刷新闪烁及appDir适配方案咨询

问题根源 #

当前代码在客户端useEffect中延迟设置主题类，而App Router的RootLayout是服务器组件，首次渲染时无法读取客户端localStorage/系统配色偏好，导致刷新时先显示默认浅色主题，再切换为深色，出现闪烁。

解决方案（基于next-themes实现，对应原博客方案适配） #

1. 安装依赖

npm install next-themes

2. 创建客户端主题提供者组件

新建app/providers.tsx（封装next-themes的ThemeProvider，App Router中服务器组件不能直接使用客户端hooks）：

'use client';

import { ThemeProvider } from 'next-themes';
import type { ReactNode } from 'react';

export default function ThemeProviders({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider
      attribute="class"       // 用class属性切换主题，对应Tailwind的darkMode: 'class'配置
      defaultTheme="system"   // 默认跟随系统配色
      enableSystem           // 启用系统配色检测
      disableTransitionOnChange  // 切换主题时禁用过渡效果，避免闪烁
    >
      {children}
    </ThemeProvider>
  );
}

3. 修改根布局app/layout.tsx

导入主题提供者并包裹内容，同时添加suppressHydrationWarning避免服务器/客户端渲染不一致的警告：

import ThemeProviders from './providers';
import Darkmode from './darkmode';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head />
      <body>
        <ThemeProviders>
          <button className='h-8 w-8 p-1 bg-blue-300 dark:bg-red-600 rounded-full'>
            <Darkmode />
          </button>
          {children}
        </ThemeProviders>
      </body>
    </html>
  );
}

4. 简化主题切换组件app/darkmode.tsx

用next-themes的useTheme钩子替代手动状态管理，自动同步localStorage和系统偏好：

'use client';

import { useTheme } from 'next-themes';

function Darkmode() {
  const { theme, setTheme } = useTheme();

  const toggleTheme = () => {
    setTheme(theme === 'dark' ? 'light' : 'dark');
  };

  return (
    <div className='h-6 w-6 cursor-pointer' onClick={toggleTheme}>
      {theme === 'dark' ? 'Light' : 'Dark'}
    </div>
  );
}

export default Darkmode;

5. 确认Tailwind配置

确保tailwind.config.js中开启class模式的暗黑主题：

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class',
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

手动实现（无需第三方库） #

若不想依赖next-themes，可在根布局的<head>中添加内联脚本，在页面渲染前立即设置主题类：

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
                document.documentElement.classList.add('dark')
              } else {
                document.documentElement.classList.remove('dark')
              }
            `,
          }}
        />
      </head>
      <body>
        <button className='h-8 w-8 p-1 bg-blue-300 dark:bg-red-600 rounded-full'>
          <Darkmode />
        </button>
        {children}
      </body>
    </html>
  );
}

同时调整darkmode.tsx的状态同步逻辑，确保切换主题时更新localStorage和DOM类名即可。

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