Next.js 13中Jotai useHydrateAtoms钩子引发Hydration错误的解决方法

核心原因 #

Hydration错误的本质是服务端渲染的DOM内容与客户端首次Hydration阶段渲染的内容不匹配：

• 服务端渲染时，ChildComponent使用传入的initialState生成DOM；
• 客户端Hydration阶段，useHydrateAtoms还未生效，useAtom读取的是原子的默认值（通常为null或空对象），导致渲染内容和服务端不一致，触发错误。

方案1：Hydration完成前使用Props值，之后切换到原子状态 #

通过useState跟踪Hydration完成状态，确保客户端首次渲染与服务端输出一致，完成后再使用Jotai原子的状态：

步骤1：定义带兼容默认值的原子 #

// atoms.js
import { atom } from 'jotai';

// 设置与服务端返回数据结构一致的默认值，避免渲染时出现null/undefined访问
export const myAtom = atom({ id: '' });

步骤2：修改客户端组件 #

"use client";

import { useHydrateAtoms, useAtom } from 'jotai';
import { useEffect, useState } from 'react';
import { myAtom } from './atoms';

export function ChildComponent({ initialState }) {
  const [hydrated, setHydrated] = useState(false);
  // 执行原子 hydration
  useHydrateAtoms([[myAtom, initialState]]);
  const [data, setData] = useAtom(myAtom);

  // Hydration完成后更新状态标记
  useEffect(() => {
    setHydrated(true);
  }, []);

  // Hydration完成前用props的initialState，之后用原子数据
  const renderData = hydrated ? data : initialState;

  return <>{renderData.id}</>;
}

方案2：用useEffect延迟设置原子初始值 #

放弃useHydrateAtoms，改用useEffect在Hydration完成后设置原子的初始值，确保客户端首次渲染始终使用props的initialState：

"use client";

import { useAtom } from 'jotai';
import { useEffect } from 'react';
import { myAtom } from './atoms';

export function ChildComponent({ initialState }) {
  const [data, setData] = useAtom(myAtom);

  // Hydration完成后将服务端数据写入原子
  useEffect(() => {
    setData(initialState);
  }, [initialState, setData]);

  // 始终用initialState渲染服务端输出的内容，原子状态仅用于后续交互更新
  return <>{initialState.id}</>;
}

这种方法更简洁，缺点是原子会先使用默认值，之后再更新为initialState，可能会触发一次额外重渲染，但不会导致Hydration错误。

方案3：使用Jotai的atomWithDefault结合服务端传递的初始值 #

如果需要原子默认值直接依赖服务端数据，可以通过atomWithDefault结合上下文传递，天然避免Hydration不匹配：

步骤1：创建上下文传递服务端初始值 #

// contexts.js
import { createContext, useContext } from 'react';

export const InitialDataContext = createContext(null);

步骤2：服务端组件提供上下文 #

// page.js
import { InitialDataContext } from './contexts';
import ChildComponent from './ChildComponent';

const getData = async () => {
  // 获取服务端数据
  return { id: '123' };
};

export default async function Page() {
  const data = await getData();
  return (
    <InitialDataContext.Provider value={data}>
      <ChildComponent />
    </InitialDataContext.Provider>
  );
}

步骤3：定义依赖上下文的原子 #

// atoms.js
import { atomWithDefault } from 'jotai/utils';
import { useContext } from 'react';
import { InitialDataContext } from './contexts';

export const myAtom = atomWithDefault(() => {
  const initialData = useContext(InitialDataContext);
  return initialData || { id: '' };
});

步骤4：客户端组件直接使用原子 #

"use client";

import { useAtom } from 'jotai';
import { myAtom } from './atoms';

export function ChildComponent() {
  const [data, setData] = useAtom(myAtom);
  return <>{data.id}</>;
}

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