React 中 key 的作用

React 中 key 的作用是什么？

Date: August 31, 2025
Area: 原理

key 概念

在 React 中，key 用于识别哪些元素是变化、添加或删除的。

在列表渲染中，key 尤其重要，因为它能提高渲染性能和确保组件状态的一致性。

key 的作用

1）唯一性标识：

React 通过 key 唯一标识列表中的每个元素。当列表发生变化（增删改排序）时，React 会通过 key 快速判断：

哪些元素是新增的（需要创建新 DOM 节点）
哪些元素是移除的（需要销毁旧 DOM 节点）
哪些元素是移动的（直接复用现有 DOM 节点，仅调整顺序）

如果没有 key，React 会默认使用数组索引（index）作为标识，这在动态列表中会导致 性能下降 或 状态错误。

2）保持组件状态：

使用 key 能确保组件在更新过程中状态的一致性。不同的 key 会使 React 认为它们是不同的组件实例，因而会创建新的组件实例，而不是重用现有实例。这对于有状态的组件尤为重要。

// 如果初始列表是 [A, B]，用索引 index 作为 key：
<ul>{items.map((item, index) => (<li key={index}>{item}</li>))}
</ul>// 在头部插入新元素变为 [C, A, B] 时：
// React 会认为 key=0 → C（重新创建）
// key=1 → A（复用原 key=0 的 DOM，但状态可能残留）
// 此时，原本属于 A 的输入框状态可能会错误地出现在 C 中。

3）高效的 Diff 算法：

在列表中使用 key 属性，React 可以通过 Diff 算法快速比较新旧元素，确定哪些元素需要重新渲染，哪些元素可以复用。这减少了不必要的 DOM 操作，从而提高渲染性能。

源码解析

以下是 React 源码中与 key 相关的关键部分：

1）生成 Fiber树

在生成 Fiber 树时，React 使用 key 来匹配新旧节点。

src/react/packages/react-reconciler/src/ReactChildFiber.js

Code:

    // * 协调子节点，构建新的子fiber结构，并且返回新的子fiberfunction reconcileChildFibers(returnFiber: Fiber,currentFirstChild: Fiber | null, // 老fiber的第一个子节点newChild: any,lanes: Lanes,): Fiber | null {// This indirection only exists so we can reset `thenableState` at the end.// It should get inlined by Closure.thenableIndexCounter = 0;const firstChildFiber = reconcileChildFibersImpl(returnFiber,currentFirstChild,newChild,lanes,null, // debugInfo);thenableState = null;// Don't bother to reset `thenableIndexCounter` to 0 because it always gets// set at the beginning.return firstChildFiber;}function reconcileChildrenArray(returnFiber: Fiber,currentFirstChild: Fiber | null,newChildren: Array<any>,lanes: Lanes,debugInfo: ReactDebugInfo | null,): Fiber | null {let resultingFirstChild: Fiber | null = null; // 存储新生成的childlet previousNewFiber: Fiber | null = null;let oldFiber = currentFirstChild;let lastPlacedIndex = 0;let newIdx = 0;let nextOldFiber = null;// ! 1. 从左边往右遍历，比较新老节点，如果节点可以复用，继续往右，否则就停止for (; oldFiber !== null && newIdx < newChildren.length; newIdx++) {if (oldFiber.index > newIdx) {nextOldFiber = oldFiber;oldFiber = null;} else {nextOldFiber = oldFiber.sibling;}const newFiber = updateSlot(returnFiber,oldFiber,newChildren[newIdx],lanes,debugInfo,);if (newFiber === null) {// TODO: This breaks on empty slots like null children. That's// unfortunate because it triggers the slow path all the time. We need// a better way to communicate whether this was a miss or null,// boolean, undefined, etc.if (oldFiber === null) {oldFiber = nextOldFiber;}break;}if (shouldTrackSideEffects) {if (oldFiber && newFiber.alternate === null) {// We matched the slot, but we didn't reuse the existing fiber, so we// need to delete the existing child.deleteChild(returnFiber, oldFiber);}}lastPlacedIndex = placeChild(newFiber, lastPlacedIndex, newIdx);if (previousNewFiber === null) {// TODO: Move out of the loop. This only happens for the first run.resultingFirstChild = newFiber;} else {// TODO: Defer siblings if we're not at the right index for this slot.// I.e. if we had null values before, then we want to defer this// for each null value. However, we also don't want to call updateSlot// with the previous one.previousNewFiber.sibling = newFiber;}previousNewFiber = newFiber;oldFiber = nextOldFiber;}// !2.1 新节点没了，（老节点还有）。则删除剩余的老节点即可// 0 1 2 3 4// 0 1 2 3if (newIdx === newChildren.length) {// We've reached the end of the new children. We can delete the rest.deleteRemainingChildren(returnFiber, oldFiber);if (getIsHydrating()) {const numberOfForks = newIdx;pushTreeFork(returnFiber, numberOfForks);}return resultingFirstChild;}// ! 2.2 (新节点还有)，老节点没了// 0 1 2 3 4// 0 1 2 3 4 5if (oldFiber === null) {// If we don't have any more existing children we can choose a fast path// since the rest will all be insertions.for (; newIdx < newChildren.length; newIdx++) {const newFiber = createChild(returnFiber,newChildren[newIdx],lanes,debugInfo,);if (newFiber === null) {continue;}lastPlacedIndex = placeChild(newFiber, lastPlacedIndex, newIdx);if (previousNewFiber === null) {// TODO: Move out of the loop. This only happens for the first run.resultingFirstChild = newFiber;} else {previousNewFiber.sibling = newFiber;}previousNewFiber = newFiber;}if (getIsHydrating()) {const numberOfForks = newIdx;pushTreeFork(returnFiber, numberOfForks);}return resultingFirstChild;}// !2.3 新老节点都还有节点，但是因为老fiber是链表，不方便快速get与delete，// !   因此把老fiber链表中的节点放入Map中，后续操作这个Map的get与delete// 0 1|   4 5// 0 1| 7 8 2 3// Add all children to a key map for quick lookups.const existingChildren = mapRemainingChildren(returnFiber, oldFiber);// Keep scanning and use the map to restore deleted items as moves.for (; newIdx < newChildren.length; newIdx++) {const newFiber = updateFromMap(existingChildren,returnFiber,newIdx,newChildren[newIdx],lanes,debugInfo,);if (newFiber !== null) {if (shouldTrackSideEffects) {if (newFiber.alternate !== null) {// The new fiber is a work in progress, but if there exists a// current, that means that we reused the fiber. We need to delete// it from the child list so that we don't add it to the deletion// list.existingChildren.delete(newFiber.key === null ? newIdx : newFiber.key,);}}lastPlacedIndex = placeChild(newFiber, lastPlacedIndex, newIdx);if (previousNewFiber === null) {resultingFirstChild = newFiber;} else {previousNewFiber.sibling = newFiber;}previousNewFiber = newFiber;}}// !3. 如果是组件更新阶段，此时新节点已经遍历完了，能复用的老节点都用完了，// ! 则最后查找Map里是否还有元素，如果有，则证明是新节点里不能复用的，也就是要被删除的元素，此时删除这些元素就可以了if (shouldTrackSideEffects) {// Any existing children that weren't consumed above were deleted. We need// to add them to the deletion list.existingChildren.forEach(child => deleteChild(returnFiber, child));}if (getIsHydrating()) {const numberOfForks = newIdx;pushTreeFork(returnFiber, numberOfForks);}return resultingFirstChild;}

在 reconcileChildFibers 中的关键使用：

顶层“单个元素”分支（如 reconcileSingleElement）：先在兄弟链表里按 key 查找可复用的老 Fiber；若 key 相同再比类型，复用成功则删除其他老兄弟，否则删到尾并新建。

  function reconcileSingleElement(returnFiber: Fiber,currentFirstChild: Fiber | null,element: ReactElement,lanes: Lanes,debugInfo: ReactDebugInfo | null,): Fiber {const key = element.key;let child = currentFirstChild;// 检查老的fiber单链表中是否有可以复用的节点while (child !== null) {if (child.key === key) {...if (child.elementType === elementType || ... ) {deleteRemainingChildren(returnFiber, child.sibling);const existing = useFiber(child, element.props);...return existing;}deleteRemainingChildren(returnFiber, child);break;} else {deleteChild(returnFiber, child);}}...}

顶层对 Fragment（无 key）特殊处理：若是未带 key 的顶层 Fragment，会直接把 children 取出来按数组/迭代器逻辑继续走。

2）比较新旧节点

在比较新旧节点时，React 通过 key 来确定节点是否相同：

src/react/packages/react-reconciler/src/ReactChildFiber.js

Code:

  function updateSlot(returnFiber: Fiber,oldFiber: Fiber | null,newChild: any,lanes: Lanes,debugInfo: null | ReactDebugInfo,): Fiber | null {// Update the fiber if the keys match, otherwise return null.const key = oldFiber !== null ? oldFiber.key : null;if ((typeof newChild === 'string' && newChild !== '') ||typeof newChild === 'number') {// Text nodes don't have keys. If the previous node is implicitly keyed// we can continue to replace it without aborting even if it is not a text// node.if (key !== null) {return null;}return updateTextNode(returnFiber,oldFiber,'' + newChild,lanes,debugInfo,);}if (typeof newChild === 'object' && newChild !== null) {switch (newChild.$$typeof) {case REACT_ELEMENT_TYPE: {if (newChild.key === key) {return updateElement(returnFiber,oldFiber,newChild,lanes,mergeDebugInfo(debugInfo, newChild._debugInfo),);} else {return null;}}case REACT_PORTAL_TYPE: {if (newChild.key === key) {return updatePortal(returnFiber,oldFiber,newChild,lanes,debugInfo,);} else {return null;}}case REACT_LAZY_TYPE: {const payload = newChild._payload;const init = newChild._init;return updateSlot(returnFiber,oldFiber,init(payload),lanes,mergeDebugInfo(debugInfo, newChild._debugInfo),);}}if (isArray(newChild) || getIteratorFn(newChild)) {if (key !== null) {return null;}return updateFragment(returnFiber,oldFiber,newChild,lanes,null,mergeDebugInfo(debugInfo, newChild._debugInfo),);}// Usable node types//// Unwrap the inner value and recursively call this function again.if (typeof newChild.then === 'function') {const thenable: Thenable<any> = (newChild: any);return updateSlot(returnFiber,oldFiber,unwrapThenable(thenable),lanes,debugInfo,);}if (newChild.$$typeof === REACT_CONTEXT_TYPE) {const context: ReactContext<mixed> = (newChild: any);return updateSlot(returnFiber,oldFiber,readContextDuringReconcilation(returnFiber, context, lanes),lanes,debugInfo,);}throwOnInvalidObjectType(returnFiber, newChild);}if (__DEV__) {if (typeof newChild === 'function') {warnOnFunctionType(returnFiber, newChild);}if (typeof newChild === 'symbol') {warnOnSymbolType(returnFiber, newChild);}}return null;}

实际案例

1）简单列表

假设我们有一个简单的列表：

const items = this.state.items.map(item => <li key={item.id}>{ item.text }</li>
)

在上述代码中，每个

元素都有一个唯一的 key。

如果 items 数组发生变化（如添加或删除元素），React将根据 key 来高效地更新DOM：

当一个元素被删除时，React仅删除对应 key 的DOM节点。
当一个元素被添加时，React 仅在相应的位置插入新的DOM节点。
当一个元素被移动时，React 会识别到位置变化并重新排列 DOM 节点。

2）错误案例演示

在这里插入图片描述

import React, { useState } from 'react'// 错误案例：使用数组索引作为 key，导致组件在插入/重排时状态错乱
// 复现实验：
// 1) 在下方两个输入框分别输入不同文本（对应 A、B）
// 2) 点击“在头部插入 C” → 列表从 [A, B] 变为 [C, A, B]
// 3) 使用 index 作为 key 时：
//    key=0 → C（重新创建）
//    key=1 → A（复用原 key=0 的 DOM，状态可能残留）
//    因此原本属于 A 的输入框状态可能会错误地出现在 C 中function InputItem({ label }: { label: string }) {const [text, setText] = useState<string>('')return (<divstyle={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 8 }}><span style={{ width: 80 }}>{label}</span><inputplaceholder="在此输入以观察状态"value={text}onChange={e => setText(e.target.value)}/></div>)
}export default function TestDemo() {const [labels, setLabels] = useState<string[]>(['A', 'B'])const prependC = () => {setLabels(prev => ['C', ...prev])}return (<div style={{ padding: 16 }}><h3>错误示例：使用 index 作为 key（头部插入触发状态错乱）</h3><button onClick={prependC} style={{ marginBottom: 12 }}>在头部插入 C</button>{labels.map((label, index) => (// 错误：使用 index 作为 key，头部插入 C 后会发生状态错位<InputItem key={index} label={label} />))}</div>)
}