Next.js13 App目录下Mantine主题切换闪烁问题求助

核心解决方案思路 #

问题根源在于服务端无法读取localStorage，导致初始渲染时Mantine只能用默认主题，客户端useEffect执行后才切换为用户偏好，引发闪烁。解决关键是让服务端能获取用户主题偏好，同时保证客户端初始状态与服务端一致，具体通过Cookie存储+服务端读取+HTML属性同步实现。

步骤1：用Cookie存储主题偏好（替代仅依赖localStorage） #

Cookie可被服务端读取，因此切换主题时需同时更新localStorage和Cookie，确保服务端渲染时能拿到用户的主题设置。

步骤2：根布局（Server Component）中注入主题配置 #

在app/layout.tsx（Server Component）中读取Cookie中的主题值，直接生成对应主题的Mantine配置，并将主题值写入HTML的data-theme属性，保证服务端渲染的HTML与用户偏好一致。

import { cookies } from 'next/headers';
import { MantineProvider, createTheme } from '@mantine/core';
import { ThemeProvider } from './components/ThemeContext';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  // 服务端读取Cookie，无值时用默认主题（比如light）
  const cookieStore = cookies();
  const userTheme = cookieStore.get('theme')?.value || 'light';

  // 创建Mantine主题
  const theme = createTheme({
    colorScheme: userTheme as 'light' | 'dark',
  });

  return (
    <html lang="zh-CN" data-theme={userTheme}>
      <body>
        <MantineProvider theme={theme}>
          <ThemeProvider>{children}</ThemeProvider>
        </MantineProvider>
      </body>
    </html>
  );
}

步骤3：客户端Theme Context实现状态同步 #

在客户端组件中，初始化状态优先读取HTML的data-theme属性（避免客户端初始渲染用默认值），切换主题时同步更新localStorage、Cookie和HTML属性，保证前后端状态统一。

'use client';

import { createContext, useContext, useEffect, useState } from 'react';
import { useMantineColorScheme } from '@mantine/core';

type ThemeContextType = {
  toggleTheme: () => void;
  currentTheme: 'light' | 'dark';
};

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

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const { colorScheme, setColorScheme } = useMantineColorScheme();
  // 客户端初始化时优先取HTML的data-theme，保证与服务端渲染一致
  const [currentTheme, setCurrentTheme] = useState<'light' | 'dark'>(
    (document.documentElement.dataset.theme as 'light' | 'dark') || 'light'
  );

  const toggleTheme = () => {
    const newTheme = currentTheme === 'light' ? 'dark' : 'light';
    setCurrentTheme(newTheme);
    setColorScheme(newTheme);
    
    // 同步更新localStorage
    localStorage.setItem('theme', newTheme);
    // 更新Cookie，让服务端下次渲染能读取
    document.cookie = `theme=${newTheme}; path=/; max-age=31536000`;
    // 更新HTML属性
    document.documentElement.dataset.theme = newTheme;
  };

  useEffect(() => {
    // 首次加载时，将localStorage的主题同步到Cookie和HTML属性
    const storedTheme = localStorage.getItem('theme') as 'light' | 'dark';
    if (storedTheme && storedTheme !== currentTheme) {
      setCurrentTheme(storedTheme);
      setColorScheme(storedTheme);
      document.documentElement.dataset.theme = storedTheme;
      document.cookie = `theme=${storedTheme}; path=/; max-age=31536000`;
    }
  }, []);

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

export const useTheme = () => {
  const context = useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
};

关键优势 #

1. 服务端预渲染正确主题：通过Cookie传递主题偏好，服务端渲染时直接生成对应用户主题的页面，彻底避免闪烁。
2. 客户端初始状态与服务端一致：读取HTML的data-theme属性初始化客户端状态，确保客户端首次渲染无偏差。
3. 状态全链路同步：切换主题时同步更新localStorage、Cookie和HTML属性，保证刷新或重新加载页面时主题一致。

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