Next.js 16使用next-themes实现明暗模式时遇脚本警告求助

问题根源 #

你遇到的警告是因为next-themes在客户端渲染的组件中注入了<script>标签，而Next.js（尤其是Turbopack模式下）会阻止组件内的脚本执行，要求改用<template>标签替代。通常这个问题出现在ThemeProvider的初始化配置不当，或者手动添加了不必要的脚本标签。

解决方案 #

1. 修正ThemeProvider.jsx的实现 #

确保你的ThemeProvider仅使用next-themes提供的官方API，不要手动插入<script>标签。正确的实现如下：

'use client';

import { ThemeProvider as NextThemesProvider } from 'next-themes';
import { useEffect, useState } from 'react';

export default function ThemeProvider({ children }) {
  const [mounted, setMounted] = useState(false);

  // 仅在客户端挂载后初始化主题
  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) {
    return <>{children}</>;
  }

  return (
    <NextThemesProvider
      attribute="class"
      defaultTheme="system"
      enableSystem
      disableTransitionOnChange
    >
      {children}
    </NextThemesProvider>
  );
}

2. 在layout.js中正确包裹根组件 #

确保ThemeProvider只在客户端组件中使用，并且正确包裹整个应用：

import ThemeProvider from './ThemeProvider';
import './global.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

注意：添加suppressHydrationWarning可以避免主题切换时的 hydration 不匹配警告。

3. 配置Tailwind v4的暗色模式 #

在tailwind.config.js中确保暗色模式设置为class，和next-themes的attribute="class"匹配：

export default {
  darkMode: 'class',
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  // 其他配置项...
};

4. 移除组件内手动添加的<script>标签 #

如果你在任何组件中手动添加了用于主题切换的<script>标签，直接删除它们，改用next-themes提供的useTheme钩子实现切换逻辑：

'use client';

import { useTheme } from 'next-themes';

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

  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      {theme === 'dark' ? '切换到亮色模式' : '切换到暗色模式'}
    </button>
  );
}

5. 验证Turbopack配置 #

确保你的next.config.js中Turbopack的配置没有干扰主题脚本执行：

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbo: true,
  },
};

export default nextConfig;

验证解决方案 #

完成以上步骤后，重启开发服务器，检查控制台是否还存在脚本警告。如果警告消失，说明问题已解决；如果仍然存在，检查是否有其他第三方组件或自定义代码注入了<script>标签，逐一排查即可。

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