JSX列表渲染为什么必须加key？key能不能用index？

一、从一个表单 Bug 看起：为什么会发生状态错位？

假设你在开发一个任务管理（Todo）组件。每个任务项由一个文本标签和一个包含内部状态的 <input> 组成，代码使用 index 作为 key 渲染列表：

function TodoList() {
  const [tasks, setTasks] = useState([
    { id: 'task-1', title: '复查需求文档' },
    { id: 'task-2', title: '编写接口测试用例' }
  ]);

  const addTaskToTop = () => {
    // 在列表头部新增一条紧急任务
    setTasks([{ id: `task-${Date.now()}`, title: '紧急线上修复' }, ...tasks]);
  };

  return (
    <div>
      <button onClick={addTaskToTop}>在顶部添加任务</button>
      <ul>
        {tasks.map((item, index) => (
          // 错误示范：使用 index 作为 key
          <li key={index}>
            <span>{item.title}</span>
            <input placeholder="填写进度备注..." />
          </li>
        ))}
      </ul>
    </div>
  );
}

此时在页面上操作：首先在第一项“复查需求文档”的输入框中输入 进度已完成 80%。接着点击“在顶部添加任务”按钮向头部插入“紧急线上修复”。

这时候会出现令人震惊的现象：原本属于“复查需求文档”的 进度已完成 80%，居然跑到了最上方的“紧急线上修复”输入框里！而原来的“复查需求文档”反而变成了空白或错位的状态。

这个现象正是由于 key={index} 破坏了 React 虚拟 DOM 身份追踪所致。要彻底理解这一问题，必须深入 React Diff 算法的匹配机制。

二、React Diff 算法如何利用 key 识别节点？

在 React 进行协调（Reconciliation）时，为了在 O(n) 时间复杂度内高效完成虚拟 DOM 的更新比对，React 制定了两条基本假设：

1. 两个不同类型的元素会产生不同的树（直接销毁旧树，挂载新树）；
2. 开发者可以通过提供 key 属性来标识哪些同级子元素在不同渲染中是稳定一致的。

当父组件重新渲染时，React 会对比新旧两组子虚拟节点（Children Fiber 链表）。此时，key 就是节点的身份证号。

1. 缺乏唯一 Key（使用 Index）时的 Diff 行为

当旧数组是 [A, B, C]，头部插入 X 变成 [X, A, B, C] 时，对应的索引发生了改变：

• 比对第 0 位（key=0）：旧节点是 A，新节点是 X。React 检查发现 key 都是 0 且标签都是 <li>，便认定“节点没有变，只是内容属性改了”。于是它选择原地复用旧的 DOM 实例，仅仅把里面的文本内容从 A 更新为 X；
• 比对第 1 位（key=1）：旧节点是 B，新节点是 A。React 同样认定节点没变，把原本显示 B 的 DOM 实例更新为显示 A；
• 比对第 2 位（key=2）：将原本显示 C 的 DOM 实例更新为显示 B；
• 比对第 3 位（key=3）：发现旧列表中没有 index 为 3 的节点，于是新建一个 DOM 节点插入末尾，显示 C。

在这种比对逻辑下，React 误以为每一个原有节点的内容都被修改了，不仅执行了 3 次原地更新和 1 次新建，而且将 DOM 节点的位置绑定与数据本身彻底打乱。

2. 拥有稳定唯一 Key 时的 Diff 行为

如果每个元素拥有唯一的 key（如 key="a"、key="b"、key="c"），新列表则是 [key="x", key="a", key="b", key="c"]：

1. React 会先在内部建立一个根据旧 key 索引现有 Fiber 节点的 Map 字典：{ "a": Fiber_A, "b": Fiber_B, "c": Fiber_C }；
2. 遍历新列表时，遇到 key="x"，在 Map 中找不到匹配项，准确判断出这是一个新增项，立即调用底层 DOM API 创建并插入；
3. 继续遍历到 key="a"，在 Map 中快速命中对应的旧节点 Fiber_A。React 发现内容未变，仅需保留 Fiber_A 的 DOM 实例及其所有内部状态，在真实 DOM 树中将其平移即可；
4. 同理快速复用 b 和 c。

在唯一 key 机制下，React 准确实现了“1 次新增插入 + 3 次 DOM 引用移动”，零多余重绘，完全保护了节点的上下文状态。

三、key 选用 index 带来的两大致命隐患

许多初学者认为“既然用了 index 界面也能渲染出来，控制台也不报 warning，为什么不能用？”实际上，使用 index 会潜藏两个极具破坏性的隐患：

四、key 到底能不能用 index？唯一合法的 3 个准入条件

在 React 官方文档中，对于使用 index 作为 key 规定了非常严苛的前提。只有当你的列表同时满足以下 3 个条件时，使用 index 才是安全且被允许的：

• 1

  列表项是纯静态展示，永无增、删、排、滤

  该列表在组件的整个生命周期中不会发生顺序变动，不会在任意位置插入新数据，也不会删除既有数据，没有倒序或排序逻辑。

• 2

  列表项没有任何内部状态或非受控元素

  每个子项是纯展示型组件（Pure Presentational Component），不包含表单控件（input、checkbox 等）、不包含自身的 useState / useReducer、不维护展开/收起等交互状态。

• 3

  数据项中确实无法提取或生成任何业务 ID

  数据源本身是纯原始类型数组（如静态星级 ['★', '★', '★'] 或固定面包屑导航），且无法从内容拼接出稳定标识。

只要上面 3 条中有任何 1 条不满足，就严禁使用 index。

五、如何正确选择与生成稳定的 key？

为了在实际工程中杜绝此类隐患，开发者应遵循以下清晰的决策逻辑与代码规范：

最佳实践 1：优先采用后端返回的业务唯一标识

数据库实体主键（如 item.id、item.uuid）具备跨渲染生命周期的绝对唯一性和不变性，是作为 key 的首选标准：

// 推荐标准规范
<ul>
  {userList.map((user) => (
    <li key={user.id}>
      <Avatar src={user.avatarUrl} />
      <span>{user.username}</span>
    </li>
  ))}
</ul>

最佳实践 2：无直接 ID 时，使用复合唯一键

如果数据项没有直接暴露 id，但某些属性组合后具备同级唯一性，可以拼接成复合字符串：

// 使用复合稳定属性拼接
<div>
  {scheduleItems.map((item) => (
    <Card key={`schedule-${item.date}-${item.slot}`} data={item} />
  ))}
</div>

最佳实践 3：客户端动态生成的列表，在创建时固化 ID

当用户在前端主动点击“新增一项”创建本地临时数据时，应当在数据对象被实例化的时刻生成唯一 ID（例如调用 crypto.randomUUID()），并将 ID 存入数据模型本身：

// 正确做法：在生成数据项时即赋予稳定 ID
const handleAddItem = () => {
  const newItem = {
    id: crypto.randomUUID(), // 永久固化在该数据项上
    text: '新输入项',
    createdAt: Date.now()
  };
  setItems((prev) => [newItem, ...prev]);
};

// 渲染时直接读取固化的 item.id
<ul>
  {items.map((item) => (
    <TodoItem key={item.id} data={item} />
  ))}
</ul>

六、全维度对比与总结

为了方便记忆与在代码评审（Code Review）中进行规范检验，下表对常见的三种 key 传递方案进行了全方位量化总结：

总结来说，key 是 React 理解虚拟 DOM 拓扑结构变迁的“神经中枢”。保持 key 的唯一性与稳定性，既是防范表单状态错位隐蔽 Bug 的防火墙，也是保障复杂前端应用丝滑渲染性能的基石。