Next.js 15 + React 19：useOptimistic购物车上下文 hydration 错误解决

错误原因分析 #

React 19对乐观状态更新的触发时机做了严格限制：这类更新必须在startTransition或React Action（如useActionState、表单Action）中执行。如果直接在普通函数或组件挂载阶段触发，会导致服务端渲染的初始状态与客户端更新后的状态不匹配，从而触发Hydration错误，错误提示：

An optimistic state update occurred outside a transition or action. To fix, move the update to an action, or wrap with startTransition.

解决方案 #

方案1：用startTransition包裹乐观更新（快速修复） #

直接修改addCartItem函数，将updateOptimisticCart调用包裹在startTransition中，告诉React这是一个非紧急的状态更新，不会阻塞渲染，同时符合React 19的规则：

import { useCallback, startTransition } from 'react';

const addCartItem = useCallback(
  (variant: ProductVariant, product: Product) => {
    startTransition(() => {
      updateOptimisticCart({type: 'ADD_ITEM', payload: {variant, product}});
    });
  },
  [updateOptimisticCart],
);

方案2：迁移到React 19 Action模式（最佳实践） #

如果addCartItem是由用户交互（如点击按钮）触发，推荐将其转为React 19的Action，这更贴合React 19的新特性，同时能更好地处理乐观更新与实际API请求的联动：

import { useActionState } from 'react';

// 定义Action函数，处理乐观更新与API请求
async function addItemAction(state, { variant, product }) {
  // 先执行乐观更新
  updateOptimisticCart({type: 'ADD_ITEM', payload: {variant, product}});
  
  try {
    // 执行实际的添加购物车API请求
    await fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ variantId: variant.id, productId: product.id })
    });
    return { ...state, success: true, error: null };
  } catch (err) {
    // 请求失败时回滚乐观更新
    updateOptimisticCart({type: 'REMOVE_ITEM', payload: {variantId: variant.id}});
    return { ...state, success: false, error: '添加购物车失败' };
  }
}

// 在组件中使用Action
function AddToCartButton({ variant, product }) {
  const [state, formAction] = useActionState(addItemAction, { success: false, error: null });

  const handleClick = () => {
    formAction({ variant, product });
  };

  return (
    <button onClick={handleClick} disabled={state.success}>
      {state.success ? '已添加' : '加入购物车'}
      {state.error && <span className="error">{state.error}</span>}
    </button>
  );
}

额外注意事项 #

如果addCartItem是在组件挂载时自动触发（比如从localStorage恢复购物车），必须确保只在客户端执行，用useEffect包裹，避免服务端渲染时触发状态更新：

import { useEffect } from 'react';

useEffect(() => {
  const savedCart = localStorage.getItem('cart');
  if (savedCart) {
    const cartItems = JSON.parse(savedCart);
    startTransition(() => {
      cartItems.forEach(item => addCartItem(item.variant, item.product));
    });
  }
}, [addCartItem]);

内容的提问来源于stack exchange，提问作者GʀᴜᴍᴘʏCᴀᴛ