一、背景：为什么需要"传送门"

在 Vue 组件树体系中，子组件的 DOM 默认始终嵌套在父组件内部。然而，许多场景要求我们将内容“搬运”到组件树之外的指定 DOM 节点进行渲染——例如模态框、对话框，它们通常依赖 position: fixed 定位，却常因父级 overflow:hidden、transform 或 z-index 样式而产生布局冲突。此外，Toast 通知、全局提示、浮层菜单、下拉列表、Tooltip 提示框，乃至跨布局区域的内容注入（如将某块内容“投递”到页脚插槽），都面临类似需求。

这类需求的核心逻辑十分清晰：逻辑归属仍属于原组件，但渲染位置需要脱离当前组件树——这便是“传送门（Portal）模式”的典型应用场景。

二、Vue2 方案：portal-vue 库

Vue2 官方并未内置传送门功能，社区中公认的解决方案是 portal-vue 库（v2 版本适配 Vue2）。该库提供了一对协同工作的组件：

1. 基本用法

与 通过相同的字符串名称进行匹配， 所在位置即为内容渲染的目标区域。

2. portal-target 常用配置

默认情况下，一个 target 只能接收最后一个 portal 的内容（后到达的会覆盖先到达的），若需接收多个 portal 的内容，必须显式设置 multiple：

3. Vue2 + portal-vue 的典型痛点

1. 强依赖第三方库：portal-vue 体积相对较大，且需与 Vue2 版本严格匹配（v2 库对应 Vue2，v3 库对应 Vue3），版本升级成本较高。
2. SSR 需特殊处理：服务端渲染时，portal 内容默认不会出现在 HTML 中（库提供了 SSRegress 等机制），配置较为繁琐，容易踩坑。
3. 调试困难：内容在组件树 A 中定义，却渲染在组件树 B 的节点中，Vue DevTools 中父子关系被割裂，定位问题需跨树查找。
4. wrapper 嵌套：portal-target 默认会包裹一层

   ，可能破坏预期的样式效果（需通过 slim 规避），且多个 portal 时 DOM 结构不够直观。

5. 单根限制：Vue2 模板要求单一根节点，在配合传送编写复杂内容时不够灵活。
6. 响应式/重渲染逻辑隐式：portal 内容的更新依赖库的订阅机制，偶尔会出现“内容不刷新”的问题，需要排查 target 的注册时机。

三、Vue3 方案：内置

Vue3 官方内置了 组件，将“传送门”作为一等公民直接纳入框架，从根本上解决了上述痛点。

1. 基本用法

to 属性可以是任意 CSS 选择器（例如 "#modal-root"、"body"、".some-class"），也可以是一个真实的 HTMLElement 对象。

2. Vue3 的针对性优化点

3. 进阶能力

defer（Vue 3.1+）：延迟到组件挂载后再查找目标元素，有效解决“目标节点在初始渲染时尚未存在”的问题（典型场景：目标由其他异步组件动态创建）。

  目标节点尚未出现，挂载完成后再搬移过去

多 Teleport 同名合并：多个 不会相互覆盖，而是依次成为 body 的子节点，效果等同于 portal-vue 开启 multiple，但无需任何额外配置。

禁用传送保留原位渲染：

  
...

四、迁移建议（Vue2 → Vue3）

1. 卸载 portal-vue，移除所有 和 。
2. 发送端改写：将 替换为 （注意 to 仍是名称字符串，但表示选择器，建议改为真实 DOM 选择器如 #x 更直观）。
3. 接收端删除： 不再需要—— 直接将内容渲染到 to 指向的 DOM 节点，无需显式声明 target 占位符。
4. 多源场景：原先依赖 multiple 拼接的内容，直接编写多个 即可，删除 multiple 属性。
5. 条件渲染：原先通过动态 to 或销毁 portal 实现“留在原位”的逻辑，改用 :disabled 属性。
6. SSR 项目：移除 SSRegress 相关配置，Teleport 已原生支持服务端渲染。
7. slim/wrapper 清理：原来为消除包裹 div 而使用的 slim 配置可删除，Teleport 本身不引入任何包裹节点。

迁移对照表

  
hi






  
hi

五、一句话总结

从 Vue2 的 portal-vue 到 Vue3 内置的 ，不仅仅是名称的变更，更是一次从“第三方补丁”到“框架原生能力”的质的飞跃。迁移时只需去掉发送端与接收端的成对组件，改用 Teleport to 直接指向目标 DOM 节点，再配合 disabled、defer 等内建特性，整个传送门的使用体验终于变得清爽、可控且无副作用。