Vue.js 中自定义元素水合时使用 key 属性导致意外重新挂载的问题分析

问题背景

在 Vue.js 3.4.38 版本中，开发者在服务端渲染(SSR)场景下使用自定义元素(custom elements)时发现了一个有趣的现象：当为自定义元素添加 key 属性进行水合(hydration)时，会导致子组件意外地重新挂载，并丢失父组件提供的上下文(如 inject 注入的值)。

现象描述

具体表现为：

1. 子组件会在水合过程中被卸载(unmount)然后重新挂载(mount)
2. 重新挂载后，子组件无法获取到父组件通过 provide/inject 机制提供的值
3. 当移除自定义元素上的 key 属性后，一切恢复正常

技术原理分析

这个问题涉及到 Vue.js 的几个核心机制：

1. 水合过程(Hydration)：这是 SSR 中将静态 HTML 转换为交互式 Vue 应用的关键步骤。Vue 会尝试将现有的 DOM 节点与虚拟 DOM 进行匹配。

2. 自定义元素处理：Vue 对自定义元素的处理与常规组件不同，它会将大部分属性(包括 key)作为 DOM 属性直接设置到元素上。

3. 虚拟 DOM 比对算法：在 patch 过程中，Vue 会使用 isSameVNodeType 函数来判断两个虚拟节点是否是同一类型。这个判断会考虑组件的类型和 key 属性。

问题根源

问题的根本原因在于水合过程中的虚拟 DOM 比对：

1. 服务端渲染时，生成的 HTML 中自定义元素没有 key 属性
2. 客户端水合时，Vue 尝试将带有 key 属性的虚拟节点与不带 key 属性的 DOM 节点匹配
3. 由于 isSameVNodeType 认为这两个节点不同(一个有 key，一个没有)，触发卸载旧节点、挂载新节点的流程
4. 在重新挂载过程中，父组件的上下文信息丢失

解决方案

目前有以下几种解决方案：

1. 避免在自定义元素上使用 key 属性：这是最简单的解决方法，如果业务允许的话。

2. 服务端渲染时预先添加 key 属性：确保服务端和客户端渲染的 DOM 结构完全一致，包括 key 属性的存在。

3. 使用其他唯一标识方式：如果确实需要唯一标识，可以考虑使用 data-* 属性或其他自定义属性。

最佳实践建议

对于使用 Vue.js 自定义元素的开发者，建议：

1. 在 SSR 场景下谨慎使用 key 属性
2. 确保服务端和客户端渲染的 DOM 结构尽可能一致
3. 对于需要保持状态的元素，考虑使用 Vue 组件而非自定义元素
4. 在复杂场景下，可以通过自定义指令来实现更精细的控制

总结

这个问题展示了 Vue.js 在复杂场景下(SSR + 自定义元素 + key 属性)可能出现的一些边界情况。理解虚拟 DOM 比对机制和水合过程对于解决这类问题至关重要。开发者在使用这些高级特性时，需要特别注意它们之间的交互方式。