如何修复Next.js 13的Hydration错误：初始UI与服务端渲染不匹配

核心问题分析 #

你遇到的Hydration failed because the initial UI does not match what was rendered on the server错误，主要由两个原因导致：

1. RootLayout结构不符合规范：Next.js 13要求<html>标签的直接子元素只能是<head>和<body>，你当前的布局将ApolloWrapper、Provider放在了<html>内部、<body>外部，导致服务端生成的HTML结构与客户端渲染的DOM结构不匹配。
2. Session状态前后不一致：服务端渲染时useSession()初始返回undefined，客户端Hydrate阶段可能已获取到session数据，导致input的placeholder和disabled属性在服务端与客户端渲染结果不同。

修复步骤 #

1. 修正RootLayout结构 #

将所有Provider组件移至<body>内部，确保<html>的直接子元素只有<body>（Next.js会自动处理<head>内容）：

// layout.tsx
import './globals.css';
import { Inter } from 'next/font/google';
import Provider from '@/components/provider';
import {ApolloWrapper} from '../apollo-client';
import Header from '@/components/Header';

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <ApolloWrapper>
          <Provider>
            <Header />
            {children}
          </Provider>
        </ApolloWrapper>
      </body>
    </html>
  );
}

2. 同步Session状态避免UI不匹配 #

修改PostBox组件，确保客户端Hydrate完成后再渲染依赖session的内容，避免服务端与客户端UI差异：

// PostBox.tsx
"use client";

import { useSession } from "next-auth/react";
import React, { useEffect, useState } from "react";
import Avatar from "./Avatar";

function PostBox() {
  const { data: session } = useSession();
  const [clientSession, setClientSession] = useState(session);

  // 确保客户端Hydrate后再更新session状态
  useEffect(() => {
    setClientSession(session);
  }, [session]);

  return (
    <form>
      <label className="flex items-center space-x-3">
        <Avatar />
        <input
          disabled={!clientSession}
          className="flex-1 rounded-md bg-gray-50 p-2 pl-5 outline-none"
          type="text"
          placeholder={clientSession ? "Create a post" : "Sign in to post"}
        />
      </label>
    </form>
  );
}

export default PostBox;

3. 优化页面渲染逻辑 #

移除page.tsx中不必要的mounted状态，改用Next.js的Suspense处理异步状态加载：

// page.tsx
import PostBox from "@/components/PostBox";
import { Suspense } from "react";

export default function Home() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <PostBox />
    </Suspense>
  );
}

验证修复 #

完成上述修改后，重新启动开发服务器，Hydration错误应该会消失。核心是保证服务端与客户端渲染的DOM结构完全一致，同时避免在Hydration阶段修改依赖客户端状态的UI元素。

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