React 崩溃：Cannot read property 'map' of undefined —— 从报错到根治的 5 分钟指南

当你在浏览器控制台看到这条红色错误：

TypeError: Cannot read property 'map' of undefined

说明代码里把 .map() 用在了 undefined 或 null 上。React 中 90% 的场景是 「期望数组，实际是空值」。本文按「定位 → 修复 → 预防」三步法，帮你 5 分钟止血。

---

一、为什么会出现这条错误？

触发时机	说明
渲染阶段	list.map(...) 时 list === undefined
异步数据	接口尚未返回，默认值为空
解构失败	const { items } = props 而 props 没传
链式调用	data?.list?.map 忘记兜底

---

二、4 个高频翻车场景 & 修复

1️⃣ 接口未返回，默认空值

function TodoList({ todos }) {
  return (
    <ul>
      {todos.map(todo => <li key={todo.id}>{todo.title}</li>)}
    </ul>
  );
}

问题：父组件初次渲染时 todos 为 undefined。
修复：给默认值

TodoList.defaultProps = {
  todos: []
};
// 或
function TodoList({ todos = [] }) { ... }

---

2️⃣ 异步请求未完成

const [data, setData] = useState(); // 初始 undefined
return <div>{data.list.map(...)}</div>; // ❌ data.list 不存在

修复：初始化为空数组 + 可选链

const [data, setData] = useState({ list: [] });
// 或
{data?.list?.map(...)}

---

3️⃣ 解构失败或拼写错误

const { products } = props; // 若 props 没有 products → undefined
return <div>{products.map(...)}</div>;

修复：

• 检查父组件传参
• 加默认值

const { products = [] } = props;

---

4️⃣ 链式 API 返回空对象

const res = await fetch('/api');
const data = await res.json(); // 后端返回 null
setData(data); // data === null

修复：兜底逻辑

setData(data || { list: [] });

---

三、根治方案：防御式编程

方案	示例
默认值	const list = props.list ?? [];
可选链	data?.list?.map(...)
类型校验	PropTypes.array.isRequired
空状态组件	{list.length ? <List /> : <Empty />}

---

四、一句话总结

任何 .map() 之前，先问自己：「它一定是数组吗？」
用「默认值 + 可选链 + 类型校验」三板斧，彻底告别 undefined.map。

---

最后问候亲爱的朋友们，并邀请你们阅读我的全新著作

📚 《 React开发实践：掌握Redux与Hooks应用 》