React Calendar出现Hydration错误，该如何解决？

核心原因与修复方案 #

1. 时区/日期计算差异 #

服务端与客户端时区不一致，会导致 react-calendar 初始渲染的日期范围、选中值等内容出现偏差，触发文本/UI 不匹配错误。

• 修复：统一使用 UTC 时区初始化日期，避免依赖系统时区：

  import { useState } from 'react';
  import Calendar from 'react-calendar';
  
  function MyCalendar() {
    // 用 UTC 初始化日期，确保服务端和客户端渲染结果一致
    const [selectedDate, setSelectedDate] = useState(new Date(Date.UTC(2024, 5, 1)));
    return <Calendar onChange={setSelectedDate} value={selectedDate} />;
  }
  

2. 依赖客户端专属 API #

react-calendar 内部可能在初始化时访问 window 等仅客户端存在的 API，服务端渲染时无法获取，导致渲染结果不一致。

• 修复一：用 useEffect 延迟组件初始化，确保在客户端环境加载：

  import { useState, useEffect } from 'react';
  import Calendar from 'react-calendar';
  
  function MyCalendar() {
    const [isClient, setIsClient] = useState(false);
  
    useEffect(() => {
      setIsClient(true);
    }, []);
  
    // 客户端环境加载前返回空或占位组件
    return isClient ? <Calendar /> : <div>加载日历中...</div>;
  }
  

• 修复二：用 Suspense 包裹组件，让 React 在客户端渲染时处理 fallback：

  import { Suspense } from 'react';
  import Calendar from 'react-calendar';
  
  function App() {
    return (
      <Suspense fallback={<div>加载日历中...</div>}>
        <MyCalendar />
      </Suspense>
    );
  }
  

3. 版本更新引入的兼容问题 #

如果近期更新了 react-calendar 或 React 版本，可能引发服务端渲染的兼容性 bug。

• 修复：回退到之前稳定运行的版本，或查看官方文档确认版本兼容：

  // package.json 中锁定版本
  {
    "dependencies": {
      "react-calendar": "^3.9.0" // 替换为之前正常运行的版本号
    }
  }
  

4. 自定义内容/样式的不一致 #

若给 react-calendar 添加了自定义日期格式化、额外文本或样式，可能因服务端与客户端执行逻辑差异导致渲染不匹配。

• 修复：确保自定义逻辑在两端执行结果一致，比如使用同一种日期格式化工具并启用 UTC 模式，避免依赖客户端样式计算。

临时应急方案 #

若以上方法未解决问题，可强制组件仅在客户端渲染（以 Next.js 为例）：

import dynamic from 'next/dynamic';

// 禁用服务端渲染该组件
const Calendar = dynamic(() => import('react-calendar'), { ssr: false });

function MyCalendar() {
  return <Calendar />;
}

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