Next.js构建报错window未定义：localStorage访问问题求助

问题现象 #

• 预渲染页面"/dashboard"时触发ReferenceError: window is not defined错误
• 以下页面导出时均出现相同错误：
  • /admin-users
  • /change-password
  • /countries
  • /dashboard
  • /feedback
  • /products
  • /user-device-mapping
  • /users
  • /login
  • /

问题原因 #

Next.js预渲染（静态生成/服务端渲染）阶段运行在Node.js环境，该环境不存在window对象。原Hook在初始化useState的回调中直接尝试访问window，导致服务端执行时报错。

修复方案 #

所有涉及window.localStorage的操作必须放在useEffect中执行（useEffect仅在客户端挂载后触发），初始化状态时直接使用传入的初始值，避免服务端执行时接触window。

修改后的useLocalStorage Hook代码 #

import { Dispatch, SetStateAction, useEffect, useState } from "react";

type UseLocalStorageReturn<T> = [T, Dispatch<SetStateAction<T>>];

const useLocalStorage = <T>(
  key: string,
  initialValue?: T
): UseLocalStorageReturn<T> => {
  // 服务端初始化时直接用初始值，不访问window
  const [storedValue, setStoredValue] = useState<T>(initialValue as T);

  // 客户端挂载后读取localStorage更新状态
  useEffect(() => {
    try {
      const storedItem = window.localStorage.getItem(key);
      const value = storedItem ? JSON.parse(storedItem) : initialValue;
      if (value !== undefined) {
        setStoredValue(value as T);
      }
    } catch (error) {
      console.error("读取localStorage失败:", error);
    }
  }, [key, initialValue]);

  const setLocalStorageValue: Dispatch<SetStateAction<T>> = (value) => {
    // 处理函数式更新的情况
    const newValue = typeof value === "function" 
      ? (value as (prev: T) => T)(storedValue) 
      : value;
    
    // 先更新本地状态
    setStoredValue(newValue);

    // 仅在客户端环境下更新localStorage
    if (typeof window !== "undefined") {
      try {
        window.localStorage.setItem(key, JSON.stringify(newValue));
      } catch (error) {
        console.error("更新localStorage失败:", error);
      }
    }
  };

  return [storedValue, setLocalStorageValue];
};

export default useLocalStorage;

使用说明 #

保持原有使用方式不变：

const [userData] = useLocalStorage('userData')

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