Next.js 14水合失败问题：服务端与客户端UI不匹配解决方案

问题根源 #

你推测的完全正确：服务端渲染时执行new Date().toLocaleDateString()会基于服务端的时区/系统时间生成字符串，而客户端hydrate时会基于用户本地时区重新计算，两者结果不一致，触发Next.js的水合校验错误。

解决方案 #

下面提供几种既能保留“显示页面渲染时间”功能，又能解决水合错误的方法：

方法1：在客户端渲染完成后更新日期（推荐） #

利用React的useEffect钩子，只在客户端渲染完成后再生成并更新日期。因为useEffect不会在服务端执行，服务端会先渲染占位内容，客户端完成hydrate后再替换为正确的本地日期，避免不匹配。

修改你的RootLayout代码：

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import { useState, useEffect } from "react";
import "./globals.css";

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const [renderDate, setRenderDate] = useState("");

  useEffect(() => {
    // 仅在客户端执行，生成本地日期
    setRenderDate(new Date().toLocaleDateString());
  }, []);

  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
      <footer>
        <p>Page Rendered on - </p>
        {renderDate || "Loading..."}
      </footer>
    </html>
  );
}

方法2：强制使用统一时区（如UTC） #

如果不需要显示用户本地时区的日期，而是希望服务端和客户端显示完全一致的日期，可以指定统一的时区参数，让两端生成相同的字符串：

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // 指定UTC时区，服务端和客户端生成的日期字符串完全一致
  const renderDate = new Date().toLocaleDateString("en-US", {
    timeZone: "UTC",
    year: "numeric",
    month: "long",
    day: "numeric",
  });

  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
      <footer>
        <p>Page Rendered on - </p>
        {renderDate}
      </footer>
    </html>
  );
}

方法3：服务端生成日期后传递给客户端 #

如果需要显示服务端的渲染时间，而非客户端本地时间，可以在服务端生成日期，然后传递给客户端使用。在App Router中，RootLayout作为Server Component可以直接生成日期，客户端hydrate时会复用服务端的结果：

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

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

// RootLayout作为Server Component，服务端生成日期
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // 服务端生成的日期，客户端hydrate时会直接复用该值
  const serverRenderDate = new Date().toLocaleDateString();

  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
      <footer>
        <p>Server Rendered on - </p>
        {serverRenderDate}
      </footer>
    </html>
  );
}

注意：如果你的RootLayout被标记为Client Component（比如使用了useState、useEffect等客户端钩子），这种方法不适用，此时建议用方法1。

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