Next.js生产构建暗色主题初始化异常问题求助

网站通过给body元素添加darkTheme类实现暗色主题，开发环境下功能完全正常，但生产构建后，首次访问或刷新页面时，RootLayout中的主题初始化逻辑未成功给body添加darkTheme类；手动切换主题后，功能恢复正常。

生产环境下Next.js的静态优化与脚本执行时机不匹配：原代码中将初始化脚本内嵌在body内部，生产构建后页面会优先完成静态渲染，脚本执行滞后于初始渲染，导致主题类未能及时生效；而手动切换主题是客户端交互触发的逻辑，不受初始渲染时机影响。

方案一：使用Next.js Script组件（推荐） #

利用Next.js官方提供的<Script>组件的beforeInteractive策略，确保主题初始化脚本在页面任何内容渲染前执行，彻底解决生产环境下的时机问题。

修改后的RootLayout代码：

import './global.css'
import './globals.scss'
import { Inter } from 'next/font/google'
import Header from '@/components/global/Header'
import Footer from '@/components/global/Footer'
import Providers from '@/components/global/Providers'
import ClientToastContainer from '@/components/global/ClientToastContainer'
import { Analytics } from '@vercel/analytics/react'
import Script from 'next/script'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
})

export const metadata = {
  title: 'Have Small Bytes',
  description: 'Byte size blogs',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const setInitialTheme = `function run() {
    let theme = window.localStorage.getItem('theme')
    if (!theme) {
      if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
        theme = 'system-dark'
      } else {
        theme = 'system-light'
      }
      window.localStorage.setItem('theme', theme)
    }
    if (theme === 'dark' || theme === 'system-dark') {
      document.body.classList.add('darkTheme')
    } else {
      document.body.classList.remove('darkTheme')
    }
  }
  run()`

  return (
    <Providers>
      <html lang="en" className={inter.className}>
        <head>
          <Script strategy="beforeInteractive" id="init-theme">{setInitialTheme}</Script>
        </head>
        <body suppressHydrationWarning={true}>
          <Header />
          {children}
          <Analytics />
          <ClientToastContainer />
          <Footer />
        </body>
      </html>
    </Providers>
  )
}

方案二：客户端组件中用useEffect初始化 #

创建独立的客户端组件，通过useEffect确保主题初始化逻辑仅在客户端执行，避免服务端渲染与客户端状态不匹配的问题。

1. 创建ThemeInitializer.tsx组件：

'use client'

import { useEffect } from 'react'

export default function ThemeInitializer() {
  useEffect(() => {
    const run = () => {
      let theme = window.localStorage.getItem('theme')
      if (!theme) {
        if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
          theme = 'system-dark'
        } else {
          theme = 'system-light'
        }
        window.localStorage.setItem('theme', theme)
      }
      if (theme === 'dark' || theme === 'system-dark') {
        document.body.classList.add('darkTheme')
      } else {
        document.body.classList.remove('darkTheme')
      }
    }
    run()
  }, [])

  return null
}

2. 在RootLayout中引入该组件：

// RootLayout.tsx
import ThemeInitializer from '@/components/global/ThemeInitializer'

// ...其他代码

export default function RootLayout({ children }) {
  return (
    <Providers>
      <html lang="en" className={inter.className}>
        <body suppressHydrationWarning={true}>
          <ThemeInitializer />
          <Header />
          {children}
          <Analytics />
          <ClientToastContainer />
          <Footer />
        </body>
      </html>
    </Providers>
  )
}

• 移除原代码中theme = ('system-dark')这类多余的括号，让代码更规范；
• 保留suppressHydrationWarning={true}，避免客户端修改body类触发的hydration不匹配警告。

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