使用Tailwind CSS和Next.js 14实现明暗主题时遭遇FOUC问题

DevOps 小满

2026-7-5

解决Next.js 14 + Tailwind CSS的明暗模式FOUC问题

针对你同时依赖系统主题偏好和手动切换按钮的场景，以下是无需使用_document.jsx的有效解决方案：

1. 用`next/script`的`beforeInteractive`策略注入即时主题脚本

这个脚本会在HTML开始解析前执行，能最快给<html>标签添加主题类，从根源避免无样式闪烁。

在你的RootLayout（app/layout.jsx）中添加：

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      {/* 主题检测脚本，beforeInteractive确保最早执行 */}
      <Script strategy="beforeInteractive">
        {`
          // 优先读取用户手动设置的主题
          const savedTheme = localStorage.getItem('theme');
          // 没有手动设置则取系统偏好
          const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
          const theme = savedTheme || systemTheme;
          
          // 给html添加对应类
          document.documentElement.classList.add(theme);
          // 若你的Tailwind配置用data-theme触发，改用下面这行
          // document.documentElement.setAttribute('data-theme', theme);
        `}
      </Script>
      <body>{children}</body>
    </html>
  );
}

2. 同步Tailwind配置与脚本逻辑

确保你的tailwind.config.js中主题切换的触发条件和脚本一致：

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class', // 对应脚本中给html加的dark/light类
  // 若用data-theme触发，改为：darkMode: ['class', '[data-theme="dark"]'],
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

3. 优化手动切换组件的状态同步

在你的主题切换客户端组件中，确保切换后立即更新<html>的类和localStorage，避免状态滞后：

'use client';

import { useEffect, useState } from 'react';

export default function ThemeToggle() {
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    // 初始化时读取当前主题
    const currentTheme = localStorage.getItem('theme') || 
      (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
    setTheme(currentTheme);
    // 确保html类和状态一致
    document.documentElement.classList.toggle('dark', currentTheme === 'dark');
  }, []);

  const toggleTheme = () => {
    const newTheme = theme === 'light' ? 'dark' : 'light';
    setTheme(newTheme);
    localStorage.setItem('theme', newTheme);
    // 立即更新html类
    document.documentElement.classList.toggle('dark', newTheme === 'dark');
  };

  return (
    <button onClick={toggleTheme}>
      {theme === 'light' ? '切换到深色模式' : '切换到浅色模式'}
    </button>
  );
}

关键注意点

不要依赖useEffect初始化主题：useEffect在组件挂载后执行，此时页面已开始渲染，必然导致闪烁。
beforeInteractive脚本是App Router中替代_document.jsx注入早期脚本的最佳方式，会被Next.js打包到初始HTML的<head>最顶部。
确保脚本逻辑和手动切换的逻辑完全一致，避免出现主题状态不一致的情况。

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

使用Tailwind CSS和Next.js 14实现明暗主题时遭遇FOUC问题

1. 用next/script的beforeInteractive策略注入即时主题脚本 #

2. 同步Tailwind配置与脚本逻辑 #

3. 优化手动切换组件的状态同步 #

关键注意点 #

1. 用`next/script`的`beforeInteractive`策略注入即时主题脚本

2. 同步Tailwind配置与脚本逻辑

3. 优化手动切换组件的状态同步

关键注意点