Next.js 13 App Router自定义布局引发Hydration Error求助

什么是Hydration Error？ #

Hydration（水合）是React将服务器渲染的静态HTML转换为可交互客户端组件的过程。当服务器输出的HTML结构与客户端React渲染出的DOM结构不匹配时，就会触发Hydration Error。

简单错误示例 #

比如直接在组件渲染时访问客户端特有的API（如window），服务器端没有这个对象，导致服务器输出的内容和客户端不一致：

// 错误代码：服务器渲染时无法访问window
function BadComponent() {
  const screenWidth = window.innerWidth;
  return <p>屏幕宽度：{screenWidth}</p>;
}

服务器渲染时会输出<p>屏幕宽度：undefined</p>，但客户端渲染时会拿到实际的屏幕宽度（比如1920），两者内容不匹配，触发Hydration Error。

修复示例 #

通过'use client'指令标记组件为客户端组件，并使用useEffect延迟访问客户端API，确保服务器和客户端初始渲染的结构一致：

'use client';
import { useState, useEffect } from 'react';

function FixedComponent() {
  const [screenWidth, setScreenWidth] = useState(0);

  useEffect(() => {
    // 仅在客户端水合完成后执行
    setScreenWidth(window.innerWidth);
  }, []);

  return <p>屏幕宽度：{screenWidth}</p>;
}

你的布局问题解决方法 #

1. 调整RootLayout的结构 #

Next.js 13 App Router的根布局（app/layout.js）要求必须直接包含<html>和<body>标签，自定义Layout不能包裹这些顶层标签，应该放在<body>内部：

// app/layout.js
import './globals.css';
import CustomLayout from './components/CustomLayout';

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        {/* 自定义Layout放在body内部 */}
        <CustomLayout>{children}</CustomLayout>
      </body>
    </html>
  );
}

2. 适配旧Layout组件到App Router #

旧的Layout组件可能存在以下不兼容问题，逐一排查修复：

• 依赖客户端API：如果Layout中直接使用window、document等，添加'use client'指令到组件顶部，并用useEffect或状态延迟访问（参考上面的修复示例）。
• 旧路由API：如果使用了next/router中的useRouter，替换为App Router的next/navigation中的useRouter，同样需要'use client'指令。
• DOM结构不一致：确保服务器渲染的DOM和客户端渲染的DOM完全匹配，避免服务器显示A元素、客户端显示B元素的情况。

3. 第三方组件兼容 #

如果Layout中使用了第三方UI库，确认其是否支持Next.js 13 App Router。不支持的话，要么升级库的版本，要么给使用该库的组件添加'use client'指令。

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