React调用API渲染列表报Cannot read properties of undefined (reading 'map')

安全阿岳

2026-8-27

问题根因

报错TypeError: Cannot read properties of undefined (reading 'map')在组件首次渲染阶段就会触发，核心原因共3个：

初始状态与接口返回结构不匹配：你给data设置的初始值是空数组[]，数组本身不存在items属性。组件首次渲染发生在接口请求发出后、响应返回前，此时执行data.items.map等价于对undefined调用map方法，直接触发报错。你在then回调里能打印出正确数据，是因为回调执行时接口已经返回、data才被赋值为接口返回的对象，但首次渲染的报错在这之前就已经触发，代码不会走到数据更新后的重渲染阶段。
JSX语法结构错误：return后的模板没有外层包裹节点，直接写大括号执行map表达式不符合React JSX单根节点的语法要求。
字段名拼写错误：代码里读取链接字段写的是item.fields.linkURL（URL全大写），但接口返回的字段名是linkUrl（Url仅首字母大写），就算map不报错，这个字段也会读取为undefined。

修复方案

把data的初始值调整为带items空数组的对象结构，和接口返回结构对齐，保证首次渲染时data.items是可调用map的数组，不会出现undefined
给JSX模板加外层包裹节点（可以用普通<div>或者React Fragment<>）
修正字段名拼写错误，和接口返回字段保持一致
补充错误状态展示，请求失败时给用户明确提示
遍历渲染列表时给列表项加唯一key属性，符合React渲染规范

修复后的完整代码：

const EventCarousel = () => {
  // 修正初始值结构，和接口返回结构对齐
  const [data, setData] = useState({ items: [] });
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    axios
      .get(
        "https://cdn.contentful.com/spaces/qqdjjpwbe10z/environments/master/entries?access_token=PRIVATE_TOKEN"
      )
      .then((res) => {
        console.log(res.data.items[0].fields.imageUrl);
        setData(res.data);
      })
      .catch((error) => {
        setError(error.message);
      })
      .finally(() => {
        setLoading(false);
      });
  }, []);

  if (loading) {
    return <p>Data is loading...</p>;
  }
  // 补充错误状态展示
  if (error) {
    return <p>数据加载失败：{error}</p>;
  }
  // 修正JSX结构，加外层包裹，修正字段名，补充key属性
  return (
    <div className="event-carousel">
      {data.items.map((item, index) => (
        <div key={item.sys?.id || index}>
          <Event
            imageUrl={item.fields.imageUrl}
            title={item.fields.title}
            text={item.fields.text}
            // 修正字段名拼写：linkUrl 不是 linkURL
            linkUrl={item.fields.linkUrl}
            location={item.fields.location}
            date={item.fields.date}
          />
        </div>
      ))}
    </div>
  );
}

补充说明：如果不想调整初始值，也可以用可选链操作符做防御性判断，写成data.items?.map(...)，但更推荐初始值和接口结构对齐的写法，长期可维护性更高。

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