NextJS中Context+useReducer购物车刷新HTML不匹配错误求助

问题根源 #

服务端渲染阶段无法访问浏览器的Cookie，所以你的initialState在服务端会把cartItems初始化为空数组，渲染出的购物车数量是0；但客户端hydrate时，Cookies.get("cartItems")能读取到本地存储的购物车数据，cartItems变成有内容的数组，购物车数量随之变化，这就导致React检测到服务端渲染的HTML与客户端渲染的文本内容不一致，抛出错误。

解决方案 #

核心思路是：让服务端和客户端初始化状态保持一致，在客户端完成hydrate后，再从Cookie中加载购物车数据并更新状态。具体步骤如下：

1. 修改初始状态 #

将initialState中的cartItems固定初始化为空数组，避免服务端与客户端初始状态差异：

const initialState = {
  darkMode: false,
  cart: {
    cartItems: [], // 服务端、客户端初始统一为空
  },
};

2. 添加加载购物车的Reducer Action #

在你的reducer中新增一个用于从Cookie加载数据的action类型：

case "LOAD_CART_FROM_COOKIE": {
  return {
    ...state,
    cart: {
      ...state.cart,
      cartItems: action.payload,
    },
  };
}

3. 在Provider中用useEffect加载Cookie数据 #

在Context的Provider组件中，使用useEffect在客户端挂载后读取Cookie并更新状态（useEffect只会在客户端执行，不会影响服务端渲染）：

import { useEffect } from 'react';
import Cookies from 'js-cookie';

function CartProvider({ children }) {
  const [state, dispatch] = useReducer(cartReducer, initialState);

  useEffect(() => {
    // 客户端挂载完成后读取Cookie
    const savedCart = Cookies.get("cartItems");
    if (savedCart) {
      dispatch({
        type: "LOAD_CART_FROM_COOKIE",
        payload: JSON.parse(savedCart),
      });
    }
  }, []); // 空依赖数组，仅执行一次

  // 其他业务逻辑...

  return (
    <CartContext.Provider value={{ state, dispatch }}>
      {children}
    </CartContext.Provider>
  );
}

4. （可选）优化初始渲染体验 #

如果担心初始显示0后跳转到实际数量的闪烁问题，可以在状态中添加加载标记：

• 更新初始状态：

const initialState = {
  darkMode: false,
  cart: {
    cartItems: [],
    isLoaded: false, // 标记是否已加载Cookie数据
  },
};

• 修改LOAD_CART_FROM_COOKIE的处理逻辑：

case "LOAD_CART_FROM_COOKIE": {
  return {
    ...state,
    cart: {
      ...state.cart,
      cartItems: action.payload,
      isLoaded: true,
    },
  };
}

• 渲染购物车数量时判断加载状态：

<nav className="w-full h-12 bg-gray-100">
  Navbar | {cart.isLoaded ? cart.cartItems.length : 0}
</nav>

这样修改后，服务端渲染的HTML与客户端初始hydrate的内容一致，后续客户端加载Cookie数据的更新属于正常的React状态更新，不会再触发文本不匹配的错误。

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