Next.js中如何避免Hydration Error？解决localStorage初始化状态问题

问题根源 #

你遇到的Hydration错误，核心原因是服务端与客户端初始状态不匹配：

• Next.js服务端渲染时没有window对象，初始状态是[]；
• 客户端渲染时，typeof window !== "undefined"为真，会读取localStorage的数据作为初始状态，导致服务端渲染的DOM和客户端初始渲染的DOM内容不一致，触发水合校验失败。
• 你后来加的useEffect虽然能在客户端挂载后更新状态，但初始渲染的状态差异已经引发了水合错误，重复的初始化逻辑还会导致额外的状态更新问题。

修复方案 #

核心思路是：让服务端和客户端的初始状态完全一致，在客户端挂载完成后再读取localStorage更新状态（此时水合已经完成，不会触发错误）。同时优化状态更新逻辑，避免闭包问题。

修改后的完整代码：

import { createContext, useEffect, useState } from 'react';

export const CartContext = createContext({});

export function CardContextProvider({ children }) {
  // 服务端和客户端初始状态统一为空数组，保证水合时内容一致
  const [cartProducts, setCartProducts] = useState([]);

  // 客户端挂载后读取localStorage，更新购物车状态
  useEffect(() => {
    const localStorageData = window.localStorage.getItem('cartProducts');
    if (localStorageData) {
      try {
        // 加try/catch避免localStorage数据格式错误导致崩溃
        setCartProducts(JSON.parse(localStorageData));
      } catch (err) {
        console.error('解析localStorage购物车数据失败:', err);
        setCartProducts([]);
      }
    }
  }, []); 

  // 购物车状态变化时，同步到localStorage
  useEffect(() => {
    window.localStorage.setItem('cartProducts', JSON.stringify(cartProducts));
  }, [cartProducts]);

  // 用函数式更新获取最新状态，避免闭包问题
  function addProduct(productId) {
    setCartProducts(prev => [...prev, productId]);
  }

  function removeProduct(productId) {
    setCartProducts(prev => prev.filter(id => id !== productId));
  }

  return (
    <CartContext.Provider value={{ cartProducts, addProduct, removeProduct }}>
      {children}
    </CartContext.Provider>
  );
}

关键改动说明 #

1. 统一初始状态：直接将cartProducts初始化为[]，服务端和客户端渲染的初始DOM完全一致，水合校验通过。
2. 客户端挂载后读取localStorage：在空依赖的useEffect中读取localStorage，此时组件已经完成水合，更新状态只会触发客户端的二次渲染，不会引发水合错误。
3. 优化状态更新逻辑：
   • addProduct和removeProduct改用函数式更新（prev => ...），确保每次更新都基于最新的状态，避免闭包导致的状态过期问题。
   • removeProduct用filter简化逻辑，比splice更符合React状态不可变的原则。
4. 增加错误处理：解析localStorage数据时加try/catch，避免数据格式错误导致页面崩溃。

额外注意事项 #

• 不要在组件初始化阶段（比如useState的初始值、组件顶层代码）直接访问window或localStorage，这些都是客户端特有的API，服务端渲染时会报错或导致状态不一致。
• 如果购物车数据需要在服务端预渲染（比如用户登录后从接口获取），可以结合getServerSideProps或getStaticProps获取数据，再通过props传递给Context，这样服务端和客户端初始状态就能保持一致。

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