NextJS中useState与Array.map()相关TypeError问题求助

问题根源 #

你遇到的两个核心问题：

1. 初始 null 导致的 map 报错：服务端渲染时，window 对象不存在，cartFromLocalStorage 赋值为 null，此时 useState 初始状态为 null，首次渲染调用 map 就会触发报错；后续客户端状态更新为数组，页面又能正常显示。
2. 水化不匹配错误：当你把服务端初始值改为 [] 或添加 cart ? ... : ... 判断时，服务端渲染的内容（空列表/空提示）和客户端读取 localStorage 后渲染的内容（可能有数据的列表）不一致，触发 NextJS 的水化校验错误。

可行解决方案 #

核心思路是保证服务端与客户端初始渲染内容一致，同时在客户端完成水化后再加载 localStorage 中的数据。修改后的代码如下：

"use client";

import Navbar from "@/components/delivery/navbar";
import { useEffect, useState } from "react";

// 定义购物车项类型，提升代码可读性
type CartItem = {
    name: string;
    imgSrc: string;
    price: number;
    id: number;
    amount: number;
};

export default function Cart() {
    // 服务端、客户端初始状态统一为空数组，避免渲染不匹配
    const [cart, setCart] = useState<CartItem[]>([]);

    // 仅在客户端执行：读取 localStorage 并更新购物车状态
    useEffect(() => {
        const savedCart = localStorage.getItem("cart");
        if (savedCart) {
            try {
                setCart(JSON.parse(savedCart));
            } catch (err) {
                console.error("解析购物车数据失败", err);
            }
        }
    }, []);

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

    return (
        <>
            <Navbar />
            <p className="text-4xl p-4">Cart</p>
            {/* 通过数组长度判断空状态，避免 null 调用 map 的问题 */}
            {cart.length === 0 ? (
                <p>No Items in Cart</p>
            ) : (
                cart.map((item) => (
                    {/* 务必使用 item 的唯一标识作为 key，不要用随机值（会导致组件重复渲染） */}
                    <div key={item.id}>
                        <p>{item.name}</p>
                        <p>{item.price}</p>
                        <p>{item.id}</p>
                        <p>{item.amount}</p>
                    </div>
                ))
            )}
        </>
    );
}

关键优化点说明 #

1. 统一初始状态：useState 初始值设为 []，服务端和客户端首次渲染都显示空列表，避免水化不匹配。
2. 客户端延迟加载：用空依赖的 useEffect 读取 localStorage，该钩子仅在客户端水化完成后执行，不会影响服务端渲染内容。
3. 合理使用列表 key：替换 crypto.randomUUID() 为 item.id，随机 key 会导致 React 频繁重建列表项，严重影响性能。
4. 空状态判断：通过 cart.length === 0 替代 cart ? ... : ...，逻辑更清晰，同时避免潜在的类型问题。

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