VNode 的 key 值冲突会导致列表元素错位、状态丢失等异常，因 Vue 依赖 key 唯一标识节点以正确复用 DOM；常见原因包括用 index、非唯一字段、动态不稳 key 或空 id 作 key。
VNode 的 key 值冲突，是指在 Vue 渲染列表时，多个节点使用了相同或重复的 key 值，导致 Vue 的虚拟 DOM diff 算法误判节点复用关系，从而引发元素错位、状态丢失、动画乱跳、输入框失焦等异常行为。这不是语法错误，也不会报错，但会在生产环境静默“发疯”。
为什么 key 冲突会让列表“乱跳”？
Vue 依赖 key 作为节点的唯一标识来决定是复用、移动还是销毁重建 DOM 元素。当 key 重复时：
- Vue 认为两个不同数据项对应同一个 DOM 节点，强行复用其状态（比如 input 的 value、展开收起状态、滚动位置）
- 后续更新中，因 key 无法准确映射数据索引，diff 过程会错误地移动、交换甚至覆盖节点
- 用户看到的现象就是：滚动后列表项顺序突变、输入文字突然跑到别的行、折叠面板莫名展开/关闭
哪些写法最容易引发 key 冲突？
常见高危模式（尤其在生产环境被忽略）：
Blender Geometry Nodes Script Generator
下载
生成Blender Python (bpy)脚本，该脚本使用node_groups API和GeometryNodeTree接口程序化地创建几何节点修改器树，用于参数化3D资产生成。
-
用
index作 key（尤其配合 filter / sort）：数组重排后 index 变化，但 key 不变 → Vue 认为“还是原来那些节点”，实际数据已错位 - 用非唯一字段作 key（如 name、title、status）：两条数据恰好同名（例如两个用户都叫“张三”），key 冲突立即发生
-
key 值动态计算但未保证稳定性：比如
:key="item.id + '_' + Date.now()"或:key="getRandomId()"，每次渲染 key 都变 → 全量重建，性能差且动画异常 -
服务端返回数据 id 为空、为 0、为 null 或字符串 '0'/'null' 时未兜底：多个 item 的
item.id都变成"0"或undefined→ 实际 key 全是"0"或"undefined"
如何快速定位和验证 key 冲突？
不靠猜，用这几步直接验证：
- 打开浏览器 Vue Devtools，在 Components 面板找到对应列表组件，展开
v-for渲染出的子组件，查看每个 VNode 的key属性值 —— 是否有重复？是否为undefined？是否全为数字0？ - 临时在模板中加一行调试：
<span style="color:red">[{{ item.id }}]</span>，和 key 值比对，看是否出现多个相同 ID 却渲染不同内容 - 模拟排序/搜索操作，观察控制台是否频繁触发
updated钩子，且 DOM 节点顺序与数据数组顺序明显不一致 - 禁用过渡动画（
<transition-group></transition-group>换成普通<div>），如果“乱跳”消失，大概率是 key 导致的复用逻辑错误而非 CSS 动画问题<h3>生产环境安全的 key 设计原则</h3> <p>不是“能用就行”，而是要满足三个条件：唯一性、稳定性、可预测性。</p> <ul> <li> <strong>首选后端返回的业务主键</strong>：如 <code>id、uuid、order_no，前提是接口约定非空且全局唯一 -
无可靠 ID 时，组合生成确定性 key：例如
:key="item.type + '-' + item.timestamp + '-' + item.index"（确保组合字段在当前列表上下文中唯一） -
强校验 + 安全兜底：在
computed或setup中预处理 key，例如：const safeKey = computed(() => item.id || `${item.name}_${item.createdAt}_${Math.abs(item.price)}`)
避免直接:key="item.id"且不做空值判断 - 禁止在 v-for 内部用 Math.random()、Date.now()、index（除非数组绝对静态）
