排查过一个特别诡异的线上bug：用户在订单列表按金额排序之后，明明在第3行把状态改成了“已发货”，一提交，状态却挂在了第5行上。前端小组排查了一下午，最后定位到的根因只有一句话——v-for循环里没写key。
对，就是那个你经常在文档里看到、却总觉得“写不写都行”的key。实际上因为不写key翻车的案例，多到可以单独开一个系列连载。这类问题的共同点是：它不报错、不崩溃、控制台干干净净，只在用户操作序列恰好踩中某个分支时，把界面状态搅得一塌糊涂。这也是为什么大家把它叫“隐形炸弹”。
这篇文章我会用实战视角，把v-for为什么必须加key的底层逻辑、几个典型的翻车现场，以及一套一劳永逸的key设计方法讲透。不玩虚的，全程都是我自己踩过坑之后的总结。
1. 一次没有key的线上事故：状态错乱的诡异现场
1.1 事故现象：改完这一行，另一个却“学会”了
先说一个最小还原例子。假设页面上有三条待办事项，每条前面有一个输入框，用户往里填了备注内容：
<li v-for="item in items"> <span>{{ item.name }}</span> <input /> </li>数据长这样：
const items = ref([ { id: 1, name: '苹果' }, { id: 2, name: '香蕉' }, { id: 3, name: '橘子' } ])用户在第一行的输入框里敲了“多买点”，然后删掉第一行数据。删除之后，列表应该剩下“香蕉”和“橘子”，但屏幕上你看到的却是：第一行的“苹果”变成了“香蕉”，第二行的“香蕉”变成了“橘子”，而第一行输入框里还残留着“多买点”这三个字。也就是说，备注内容“跑”到了新列表的第一行上。
这个现象非常迷惑。数据明明是删除了一个，DOM数量也对，连文字都变了，但输入框里的值就是不对劲。刷新页面一切正常，一旦用户做了排序、筛选、删除、插入这种操作，状态又开始乱跑。
1.2 为什么控制台静悄悄，一点都不提示
很多人第一次遇到这种bug会先怀疑插件、怀疑数据源、甚至怀疑浏览器缓存，唯独不会怀疑v-for。因为大部分前端同学是从“能跑就行”的阶段过来的，而没写key的v-for在绝大多数情况下是能跑的。
原因在于：Vue框架层面默认了“就地更新”是合法行为。它不会在控制台打出“你没写key，我要崩了”这种提示。只有在key值重复、或者key的类型不符合预期时，Vue才会在开发环境警告。而“完全没写key”这个操作，Vue会觉得“行，那我按默认策略来”，于是问题就被默认策略悄悄埋下了。
1.3 这类bug最难缠的三件事
从那次事故里我总结出三个特征，这是它比普通bug更难排查的原因：
- 复现需要特定操作顺序。直接删除一条、直接排序，可能不一定出现肉眼可见的错乱，得要用户先往输入框里写了内容，再触发列表变动，这时残留状态才暴露出来。
- 表现像“数据错了”而不是“DOM错了”。列表文字、数量都对，只是某个内部状态错位，很容易让人去查接口、查状态管理，绕一大圈。
- 刷新就消失。一旦刷新，页面重新加载，所有状态归零，现场直接蒸发。线上用户不会陪你调试，你拿到的只能是一句“反正就是不对”。
所以这类bug一旦上线，通常只能靠代码审查和经验判断来定位。这也说明，从源头搞懂key的作用，比会修bug重要得多。
2. “就地更新”的坑：没有key时Vue的默认策略
2.1 从虚拟DOM到patch，Vue到底在做什么
要理解key，先得理解Vue是怎么更新DOM的。真实DOM操作很昂贵，每改一次样式、文本、属性都有可能引发浏览器重排或重绘。所以Vue采用虚拟DOM方案：先用普通的JS对象描述页面结构，生成一棵“虚拟节点树”，每当数据变化，就再生成一棵新的虚拟节点树，然后对比新旧两棵树，算出最小的差异，最后把这些差异一次性落到真实DOM上。
这个“对比差异”的过程就叫patch。而在patch里最复杂、最容易出问题的分支，就是处理数组渲染出来的列表节点。因为数组是可变的，会增、会删、会排序，Vue必须判断：新旧列表里哪些节点是同一个东西。
判断的标准，就是key。
2.2 没有key的diff：相当于“按座位找学生”
你可以把虚拟DOM的diff想象成老师点名。没有key的时候，Vue采取的策略是只看索引位置：新旧列表的第0个节点进行对比，第1个节点进行对比，第2个节点进行对比……只要节点类型一样（比如都是li），Vue就认为“这两个节点是同一个”，直接对旧节点做原地更新，把内容改成新节点的内容。
我打个比方。这就像老师不看学生姓名，只看座位号：1号位坐了谁，我就把1号位的人当成“那个学生”。如果学生A离开，学生B挪到1号位，老师不会认为“来了个新人”，而是认为“1号位的学生变了”，于是把1号位的作业本直接翻新成B的内容。
这个策略本身是为了提高性能：能复用的DOM就不重建。但它有一个致命盲区——它完全无视了数据本身的“身份”。旧节点身上携带的DOM状态，比如输入框里的值、开关的勾选、滚动位置、组件内部的临时数据，在“就地更新”时都被原封不动地保留了下来。内容虽然换成了新数据，但状态还是旧状态的残留，于是错乱就发生了。
2.3 加了key之后：每个节点都有“身份证”
当你在v-for上写了:key="item.id"，就等于告诉Vue：列表里每一项都有一个唯一的身份证号。diff的时候，Vue会先根据key来配对新旧节点，而不是傻乎乎地按索引对比。
还是那个点名的例子。这次老师手里有一份花名册，每个学生有学号。学生A走了，学生B从2号位挪到1号位，老师一眼就能看出来：2号位B的学号没变，B还是B。于是老师决定：把B的座位搬一下就好，B桌上那本写着笔记的草稿纸也一起跟着走。这才是符合直觉的更新方式。
所以加了key之后，列表排序、增删时，Vue会找到身份匹配的旧节点进行复用，并把相应DOM移动到正确位置；实在找不到匹配的节点，才新建或删除。这样既保证了状态跟随数据走，也避免了“推倒所有节点重建”的性能浪费。
值得一提的是，Vue 2 的双端diff和 Vue 3 的基于最长递增子序列的diff，实现细节有差异，但底层逻辑一致：key就是节点身份的凭据。理解了这一点，后面所有的坑你都能自己推出来。
3. key不是写了就行：index当key的翻车案例
3.1 index是“座位号”，不是“身份”
很多朋友一开始确实写了key，但为了图省事，直接写了:key="index"，心里想的是“反正列表每个位置的index都不一样，也算唯一了吧”。
这里就踩中了第二个隐形炸弹。index是数组的索引，它反应的是位置，而不是数据身份。数据一旦发生头部的插入或删除，所有排在后面的数据索引都会整体前移或后移，原本对应的key就全变了。
比如列表是[苹果, 香蕉, 橘子]，对应的index是0、1、2。用户删掉第一行后，列表变成[香蕉, 橘子]，此时的index重新变成了0、1。那么问题来了：
- 删除前，key为1的节点是“香蕉”。
- 删除后，key为0的节点变成了“香蕉”，key为1的节点变成了“橘子”。
Vue一看：好家伙，你在旧列表里根本没找到key为0和1的节点（旧列表的key是0、1、2），那我干脆把剩下所有的节点全部销毁重建。重建本身不是末日，灾难在于销毁意味着旧的DOM状态全部丢失，而新建的节点又带着错误位置上残留的数据身份。整个列表的状态，基本就是“重新洗牌后还沾着旧牌的花色”。
3.2 组件带状态时，index key会把旧状态“绑”到新人身上
比普通DOM状态更隐蔽的，是组件内部的状态。假设每个列表项是一个子组件，组件内部有一个“展开/收起”的开关，或者一段本地缓存的表单数据：
<template> <div> <ProductCard v-for="(item, index) in productList" :key="index" :data="item" /> </div> </template>用户展开了“商品A”的详情卡片，然后在列表头部插入了一个新商品。因为index整体后移，Vue被迫重建了所有子组件。重建之后的组件虽然拿到的data是对的，但组件内部的本地状态——比如那次“展开”操作——会随着旧组件销毁而丢失，或者被复用到了原本属于其他商品的新组件上。
最典型的现象是：你明明展开了商品A，插入一条新数据后，商品B却自动展开了。这就是组件状态错配。这种问题在开发环境很难发现，因为只有当你连续操作到第三四步的时候才会暴露。
3.3 什么时候用index确实没出事
我不打算说“index绝对不能用”这种话，因为确实有些场景用了也没事。根据我的经验，同时满足以下条件时，index当key基本不会出问题：
- 列表是纯静态渲染的，从渲染完成到页面销毁，永不增删、排序、过滤；
- 列表项不包含任何内部状态，没有输入框、勾选框、折叠面板、动画状态；
- 列表项本身不是带本地状态的子组件。
比如渲染一篇文章的章节目录、渲染一组纯展示用的标签卡片，这类场景用index确实不会炸。但我的建议仍然是：即使静态列表，也尽量给一个稳定key。因为需求永远会变，今天还静态，明天老板就要加排序和筛选。你留一个稳定的id，将来就少一次踩坑机会。
4. 排查与修复：key问题怎么快速定位
4.1 一段最小复现代码，三分钟确诊
如果你怀疑手头的bug和key有关，最快的方式是搭一个最小复现demo。结构很简单：一个列表，每项一个输入框，加一个删除按钮。
<template> <div> <button @click="removeFirst">删除第一项</button> <ul> <li v-for="item in items" :key="item.id"> <span>{{ item.name }}</span> <input /> </li> </ul> </div> </template> <script setup> import { ref } from 'vue' const items = ref([ { id: 1, name: '苹果' }, { id: 2, name: '香蕉' }, { id: 3, name: '橘子' } ]) function removeFirst() { items.value.splice(0, 1) } </script>操作步骤：
- 在任意一行输入框里输入一段文字；
- 点击“删除第一项”按钮；
- 观察其他行输入框里的文字是否还在原位、是否跑到了别的行。
如果输入框的文字“跑位”了，就是典型的就地更新问题。然后把:key="item.id"改成:key="index"或不写key，再重复一遍，现象会出现得更明显。这个demo我留着一直没删，团队里谁遇到类似问题，我都直接甩给他跑一遍，比自己解释半天的效率高多了。
4.2 key重复的另一个隐藏炸弹
除了不写key和用index，还有一种情况很容易被忽略，就是key重复。最常见的是后端接口返回的数据里，id字段并不是全局唯一的。比如多个数据源合并的列表、树形结构平铺出来的节点，不同分支下可能出现相同的id。
当两个节点的key相同时，Vue会认为它们是同一个节点，控制台会打出类似的警告：
Duplicate keys found during update: ...这会导致两种后果：一是渲染出的列表数量不对，二是更新状态时“张冠李戴”。处理办法有两个方向：
- 如果是树形结构，用
parentId + item.id组合出唯一key，比如:key="parent.id + '-' + item.id"； - 如果是不同源数据合并，可以给数据打一个前缀标记，比如
:key="'user-' + item.id"和:key="'order-' + item.id"。
排查的时候不要只盯着key的书写位置，还要看运行时key的值是否真的唯一。直接在渲染函数里打日志或者用devtools检查生成的key列表，是最快的确认方式。
4.3 用key强制重置组件的另类用法
说一个反向操作。key不止能被v-for用，它也可以直接加在一个普通组件上，用来“强制重建”组件。比如我有一个带内部表单状态的弹窗SearchForm，希望每次切换项目时都清空表单，而不是保留上一次的输入：
<SearchForm :key="currentProject.id" />当currentProject.id变化时，Vue认为这个组件的key变了，于是把旧组件销毁、新建一个实例，内部状态自然归零。这个技巧在我处理多Tab切换、弹窗复用、编辑页A跳编辑页B时非常实用。很多人不知道这一点，遇到“弹窗内容切了但表单没清”的问题只会用v-if绕来绕去，其实一个动态key就解决了。
5. 稳定key怎么选：项目里的落地方案
5.1 选择key的优先级清单
根据我的实际经验，不同数据源选key的优先级可以按这个顺序来：
- 业务主键：后端返回的
id、订单号、uuid，只要保证全局唯一且不会随排序变化，这永远是最佳选择。 - 组合唯一标识：当单字段不唯一时，用多个字段拼接，如
type + ':' + id、parentId + '-' + id。注意拼接格式里带上分隔符，避免两个字段拼出相同字符串。 - 内容hash：当数据没有id，且内容相对固定时，可以对核心字段做一个简单的hash作为key。比如渲染文章列表时用标题长度加内容片段生成key。
- 首次加载生成的持久化uuid：列表数据完全没有唯一标识时，可以在数据进入页面时用
crypto.randomUUID()给每条数据临时生成一个id，并跟随数据一起维护。这里有一个细节：临时id必须在首次加载时生成一次，之后一直复用，不能每次render都重新生成，否则和随机数key没有任何区别。
顺带说一个反面教材：千万不要用对象本身当key。对象会被强制转换成字符串，结果全都变成"[object Object]"，等于所有key都一样，直接触发重复key警告，列表直接乱套。
5.2 特殊场景下的key设计细节
- 分页列表：如果你用后端分页，每页数据都带主键id，正常用id就好。但如果接口只返回当前页数据且id可能跨页重复，建议把分页页码拼进key里，比如
:key="page + '-' + item.id"，防止切换页码时状态错配。 - 树形列表：平铺树节点时，最稳的是给节点加一个全局唯一的
_nodeKey，在构建树的时候递归生成。没有这个字段时，退而求其次用父级路径拼接。 - 排序功能列表：排序的核心就是“数据身份变、位置变”，此时用id最合适。如果你现在用的是index，一排序就会触发全部节点重建，性能差是小事，子组件状态错乱才是大事。
- 优化更新的列表项：如果列表项内部做了
v-memo或shouldUpdate类优化，key的稳定性直接影响优化是否生效。key一变，整项强制重新渲染，优化直接废掉。
5.3 用工具和Code Review把问题拦在提交之前
手工检查每一处v-for不现实，所以我把约束做到了工具链里。
第一道防线是ESLint。eslint-plugin-vue推荐配置里已经包含了vue/require-v-for-key规则，团队配置只要开启了vue3-recommended或vue/recommended，没写key的代码根本提交不上去。如果你要强制禁止用index当key，可以自己写一条简单的规则，或者靠代码审查把住。
// .eslintrc.js 片段 module.exports = { extends: ['plugin:vue/vue3-recommended'] }第二道防线是review习惯。我现在有一个不成文的规矩：CV（Code Review）中看到v-for，先看key，不稳定的key直接打回。判断标准就一句话：这个key的值，会不会因为列表的增删、排序、筛选而发生变化？会发生变化的，不管他用了多花哨的语法，一律不合格。
第三道防线是自查清单。写完列表后问自己三个问题：
- 我写key了吗？还是靠运气？
- key是稳定且唯一的吗？还是随手抄了index？
- 这个key会影响到子组件的内部状态吗？
这三关都过了，基本就能把“隐形炸弹”拆得干干净净。
最后再说点我个人的习惯。现在不管谁让我review代码，只要看到v-for，我第一眼不看业务逻辑，先找key；找到之后再追一下这个key是不是稳定唯一。很多号称“零bug”的Vue代码，难点其实不在API用得多熟，而在这种细节上有没有较真。我自己真正把“就地更新”这四个字理解透，是栽在排序勾选错位那次事故之后。如果你现在还没遇到过key引起的诡异问题，不是它不存在，只是还没触发那个操作路径。趁着项目空闲，不如把每个v-for的key都过一遍，大概率能帮你避开一次凌晨三点的线上紧急修复。
