Next.js暗黑主题刷新后自动恢复浅色模式问题求助

问题现象 #

页面刷新时，暗黑主题会短暂闪烁后自动切回浅色模式，查看localStorage发现主题状态先被初始化为暗黑，随后又被修改为浅色。

已尝试方案 #

• 在UseTheme.tsx中尝试提前添加主题事件监听器，无效。
• 在_document.tsx中编写主题类名切换代码，配合UseTheme最后一个useEffect做状态追踪，未生效。
• 参考Tailwind文档修改_document.tsx，修正UseTheme中的代码错误（移除preferDarkQuery属性类型），问题仍存在。

问题根源分析 #

1. 初始状态为空导致覆盖：UseTheme中mode的初始值是空字符串，组件挂载后第二个useEffect会立即执行，此时mode为空，触发else分支移除dark类，直接覆盖了_document.tsx中脚本设置的主题。
2. localStorage值未实时更新：第一个useEffect中userPref是初始化时获取的固定值，后续localStorage变化时不会重新读取，导致主题切换逻辑失效。
3. 重复DOM操作冲突：组件和脚本都在操作document.documentElement的类名，时序问题导致互相覆盖。

修复方案 #

1. 修正UseTheme.tsx逻辑 #

调整初始状态获取逻辑，避免空值，同时简化重复操作：

import React, { useEffect, useState } from 'react';

const UseTheme = () => {
  const darkQuery = '(prefers-color-scheme: dark)';
  // 初始化时直接从localStorage或系统偏好获取主题，避免空值
  const [mode, setMode] = useState(() => {
    const userPref = window.localStorage.getItem('theme');
    if (userPref) return userPref;
    return window.matchMedia(darkQuery).matches ? 'dark' : 'light';
  });

  // 处理系统主题变化
  useEffect(() => {
    const mediaQuery = window.matchMedia(darkQuery);
    
    const handleSystemThemeChange = () => {
      // 系统主题变化时，仅当用户未设置过主题时才更新
      if (!window.localStorage.getItem('theme')) {
        const newMode = mediaQuery.matches ? 'dark' : 'light';
        setMode(newMode);
      }
    };

    mediaQuery.addEventListener('change', handleSystemThemeChange);
    return () => mediaQuery.removeEventListener('change', handleSystemThemeChange);
  }, []);

  // 主题变化时同步更新localStorage和DOM类名
  useEffect(() => {
    window.localStorage.setItem('theme', mode);
    if (mode === 'dark') {
      document.documentElement.classList.add('dark');
    } else {
      document.documentElement.classList.remove('dark');
    }
  }, [mode]);

  // 对外暴露切换方法
  const toggleTheme = () => {
    setMode(prev => prev === 'dark' ? 'light' : 'dark');
  };

  return { mode, toggleTheme };
};

export default UseTheme;

2. 优化_document.tsx脚本 #

确保脚本逻辑和组件一致，避免冲突：

import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        {/* 内联脚本直接在HTML渲染时执行，避免Next.js Script组件的潜在时序问题 */}
        <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');
            }
          `
        }} />
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

关键修复点 #

• 初始化mode时直接获取主题值，避免空状态触发错误的DOM操作。
• 拆分系统主题变化和用户主动切换的逻辑，避免互相干扰。
• 用内联脚本替代Next.js的Script组件，确保在页面渲染前优先执行，彻底消除闪烁。

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