Skip to content

列表渲染缺少 key 属性

快速摘要

你渲染列表时没有 key 属性 —— React 无法追踪哪些项变化,导致添加、删除或重排序时的 bug。

为什么发生

  • 你用 .map() 渲染列表但未给每个列表项元素传递 key 属性

  • 你用数组索引作为 key,在重排序或开头插入时会导致问题

  • key 值不唯一,导致 React 混淆项目并可能渲染错误的组件状态

最小示例

✗ 错误代码
function ItemList({ items }) {
  return (
    <ul>
      {items.map(item => (
        <li>{item.name}</li> // no key prop!
      ))}
    </ul>
  );
}
✓ 修复代码
function ItemList({ items }) {
  return (
    <ul>
      {items.map(item => (
        <li key={item.id}>{item.name}</li> // unique key
      ))}
    </ul>
  );
}

从项 ID 添加唯一 key 属性让 React 在重渲染间追踪每个元素,防止重排序时的状态丢失和渲染 bug。

如何诊断

  • 检查浏览器控制台中关于列表缺少 key 的 React 警告

  • 验证每个列表项有唯一且稳定的 key 属性,在渲染间不变

  • 如果列表可重排序、过滤或在开头插入,确保 key 不是数组索引

如何修复

  • 给每个列表项添加唯一的 key 属性,使用数据中的稳定标识符如 ID

  • 为没有自然键的项生成唯一 ID,使用 nanoid 或 uuid 等库

  • 如果列表静态且不重排序,使用数组索引作为 key 可接受但不理想

如何预防

  • 渲染列表时始终提供唯一、稳定的 key —— 使用项 ID 或生成的唯一标识符

  • 在开发环境中启用 React key 警告且永远不要忽略它 —— 它表示潜在渲染 bug

相关资源

相关术语

相关课程

← 返回语言