迁移_document.tsx至layout.tsx并处理"Extra attributes from the server"警告

之前在Next.js的Pages Router中，我通过_document.tsx运行预加载脚本来避免暗黑模式因useEffect延迟导致的闪烁问题，示例代码如下：

import Document, { Head, Main, NextScript, Html } from "next/document";
import React from "react";

function presetTheme() {
  const dark = localStorage.getItem("theme") === "dark";

  if (dark) {
    document.body.classList.add("dark");
  }
}

const themeScript = `(() => { ${presetTheme.toString()}; presetTheme() })()`;

class MyDocument extends Document {
  render() {
    return (
      <Html lang={lang}>
        <Head />
        <body>
          <script dangerouslySetInnerHTML={{ __html: themeScript, }} />
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

现在迁移到Next 13.4+的App Router后，我在layout.tsx中实现了类似逻辑，确保脚本尽早运行，但出现了警告。layout.tsx代码如下：

import "../styles/global.css";

function presetTheme() {
  const dark = localStorage.getItem("theme") === "dark";

  if (dark) {
      document.body.classList.add("dark");
  }
}

const themeScript = `(() => { ${presetTheme.toString()}; presetTheme() })()`;

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <script dangerouslySetInnerHTML={{ __html: themeScript, }} />
        <div className="mx-auto px-4">
          {children}
        </div>
      </body>
    </html>
  );
}

运行后出现的警告信息：

Warning: Extra attributes from the server: class
    at body
    at html
    at RedirectErrorBoundary (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/redirect-boundary.js:73:9)
    at RedirectBoundary (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/redirect-boundary.js:81:11)
    at NotFoundErrorBoundary (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/not-found-boundary.js:51:9)
    at NotFoundBoundary (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/not-found-boundary.js:59:11)
    at ReactDevOverlay (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/react-dev-overlay/internal/ReactDevOverlay.js:66:9)
    at HotReload (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/react-dev-overlay/hot-reloader-client.js:276:11)
    at Router (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/app-router.js:90:11)
    at ErrorBoundaryHandler (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/error-boundary.js:80:9)
    at ErrorBoundary (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/error-boundary.js:106:11)
    at AppRouter (webpack-internal:///(app-client)/./node_modules/next/dist/client/components/app-router.js:374:13)
    at ServerRoot (webpack-internal:///(app-client)/./node_modules/next/dist/client/app-index.js:154:11)
    at RSCComponent
    at Root (webpack-internal:///(app-client)/./node_modules/next/dist/client/app-index.js:171:11)

我清楚警告是因为脚本提前给body添加了class="dark"导致服务器渲染的HTML和客户端 hydration 时的DOM不一致，现在有三个疑问：

1. 能否更规范地处理该问题以避免出现警告？
2. 结合我的使用场景，是否可以安全忽略该警告？
3. 该警告是否意味着存在性能影响？

1. 更规范的处理方式 #

可以通过以下两种方法彻底消除警告：

方法一：使用next/script的beforeInteractive策略

Next.js的next/script组件支持beforeInteractive策略，能让脚本在页面 hydration 前运行，且不会触发 hydration 不匹配警告。修改后的layout.tsx代码如下：

import "../styles/global.css";
import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Script strategy="beforeInteractive">
          {`
            function presetTheme() {
              const dark = localStorage.getItem("theme") === "dark";
              if (dark) {
                document.body.classList.add("dark");
              }
            }
            presetTheme();
          `}
        </Script>
        <div className="mx-auto px-4">
          {children}
        </div>
      </body>
    </html>
  );
}

beforeInteractive策略会将脚本注入到服务器渲染的HTML头部，确保在客户端 hydration 前执行，既避免了闪烁，又不会导致 hydration 不匹配。

方法二：将根布局设为客户端组件处理主题

将根布局标记为客户端组件，直接在组件初始化时设置主题类，同时通过useEffect同步后续主题变更：

"use client";
import "../styles/global.css";
import { useEffect, useState } from "react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const [theme, setTheme] = useState(() => {
    if (typeof window !== "undefined") {
      return localStorage.getItem("theme") || "light";
    }
    return "light";
  });

  useEffect(() => {
    const body = document.body;
    theme === "dark" ? body.classList.add("dark") : body.classList.remove("dark");
    localStorage.setItem("theme", theme);
  }, [theme]);

  // 可选：添加主题切换函数
  const toggleTheme = () => setTheme(prev => prev === "dark" ? "light" : "dark");

  return (
    <html lang="en">
      <body>
        <div className="mx-auto px-4">
          {children}
        </div>
      </body>
    </html>
  );
}

注意：这种方式可能存在极短的闪烁，不如beforeInteractive脚本彻底，但能保证 hydration 匹配。

2. 是否可以安全忽略警告 #

在这个场景下，可以安全忽略警告：

• 警告本质是服务器渲染的body无class属性，客户端脚本提前添加后导致 hydration 属性不匹配，属于主动触发的预期行为；
• 该差异不会影响页面功能或用户体验，核心的暗黑模式防闪烁逻辑正常工作；
• 生产环境下该警告会被自动隐藏，仅开发环境可见。

但如果追求代码规范和无警告的开发体验，建议采用上述规范方法解决。

3. 性能影响分析 #

该警告不会带来性能影响：

• 警告只是React在 hydration 阶段的属性不匹配提示，不会中断 hydration 流程，也不会触发重复渲染；
• 脚本本身是轻量同步操作，读取localStorage和添加类的开销可忽略；
• 页面核心渲染逻辑不受影响，用户感知不到性能变化。

需要区分的是：如果是内容不匹配导致的 hydration 警告，可能触发组件树重新渲染，但本场景仅为单个属性差异，不会引发这类问题。

内容的提问来源于stack exchange，提问作者Halvor Holsten Strand