前言：Teleport 不只是 to="body"

大多数开发者初次接触 ，都是从同一段示例代码开始的：

 复制代码
  
...

将模态框传送到 下，可避开父节点的 transform、overflow:hidden、z-index 堆叠上下文问题——这是 Teleport 最经典的用法，也是官方文档前 30% 的内容。

然而，翻到 Vue 官方文档 Teleport 章节的下半部分，你会发现三个被简单提及的小节：

• Disabling Teleport
• Multiple Teleports on the Same Target
• Deferred Teleport（Vue 3.5+ 新增）

这三个部分文档总共不足 50 行正文，但在实际业务中，每一条都对应着我们踩过的多个坑：响应式断点切换、多个 Modal 互相覆盖、Tooltip 找不到目标容器、SSR 水合错位……

今天这篇文章就来把这三块“边角料”拼起来——disabled 如何优雅使用、多目标渲染顺序背后的逻辑、SSR 下水合需要注意什么、Vue 3.5 的 defer 到底为了解决什么问题。

一、disabled：被当作“开关”，实际上是“渲染位置切换器”

1.1 它做的不是“启用 / 关闭”

disabled 这个属性名，第一眼看上去像是“是否启用 Teleport”。但查阅 runtime-core 里的 Teleport.ts 类型定义：

 复制代码export interface TeleportProps {
  to: string | RendererElement | null | undefined
  disabled?: boolean
  defer?: boolean
}const isTeleportDisabled = (props: VNode['props']): boolean =>
  props && (props.disabled || props.disabled === '')

更准确的描述是：

它是一个渲染位置开关，而非“功能开关”。理解这一点，才能发现它的真正价值——响应式地切换渲染位置。

1.2 经典场景：桌面端弹层 / 移动端 inline

这是官方文档给出的例子：

 复制代码
  

桌面端 isMobile = false，菜单飞至 下渲染为下拉浮层；移动端 isMobile = true，菜单留在按钮旁作为 inline 块——这是响应式 UI 中非常自然的需求。

完整一点的实现，配合 matchMedia 可以做到真正的断点切换：

 复制代码

此处有一个值得注意的细节：disabled 由 true 切换为 false 时，已挂载的 DOM 节点是直接被 move 到目标容器，而非销毁重建。这意味着：

• 节点上的事件监听不会丢失
• 输入框的 focus 状态、视频播放进度都能保留
• 的 IME 输入态不会被打断

在源码层面，这是 moveTeleport 函数的功劳（Teleport.ts in vuejs/core）：

 复制代码// 简化版伪代码
function moveTeleport(vnode, container, anchor, internals, moveType) {
  // 不是销毁重建，而是 insert + move
  if (moveType === TeleportMoveTypes.TARGET_CHANGE) {
    insert(vnode.targetAnchor!, container, anchor)
  }
  // 遍历子节点逐个 move 到新容器
  for (const child of vnode.children) {
    move(child, container, anchor, MoveType.REORDER)
  }
}

正因为是“移动”而非“重建”，disabled 切换才能如此丝滑。这也是它比 v-if 双套写法（移动端 / 桌面端各写一份模板）优秀的地方。

1.3 一个反直觉的用法：用 disabled 做 SSR 兜底

下面这个写法，在 SSR 项目中你会经常见到：

 复制代码

它的含义是：服务端渲染时 disabled = true，内容留在原位输出；客户端 mount 后才把 disabled 切回 false，触发那次“无副作用的 move”。这种写法可以绕开许多 SSR + Teleport 的水合陷阱（后面第四节会单独讲解）。

1.4 测试场景下的 stub

单元测试中 Teleport 经常带来困扰——内容被传送到 document.body，断言时找不到。@vue/test-utils 提供了 stub 方案：

 复制代码import { mount } from '@vue/test-utils'
import Modal from './Modal.vue'const wrapper = mount(Modal, {
  props: { open: true },
  global: {
    stubs: { teleport: true },  // 等价于 disabled=true
  },
})expect(wrapper.find('.modal').exists()).toBe(true)

它实际上是把 Teleport stub 成 disabled 模式，让内容渲染在组件树中便于断言。来源：Fix: Vue Teleport Not Rendering。

二、多个 Teleport 指向同一个目标：渲染顺序的隐性约定

2.1 文档里的一句话

官方文档 对多目标的描述只有两行：

直译：后挂载的排在先挂载的后面，全部 append 到目标容器。

听起来朴素，但落到业务中——你想用一个 #modals 容器同时塞 N 个 Modal，或者用一个 #toasts 容器叠 N 条 Toast，这个“挂载顺序”就开始变得讲究了。

2.2 一个真实踩过的坑：Toast 顺序

假设有这样的需求：右下角 toast，新的总在最下面、旧的在最上面：

 复制代码

第一次推三条 toast，结果符合预期：

 复制代码<div id="toasts">
  <div class="toast">Adiv>
  <div class="toast">Bdiv>
  <div class="toast">Cdiv>
div>

但下一次只 push 一条新的 D，问题来了——D 被 append 在 C 后面没问题，但如果中间某条 B 被关掉，再 push 一条 E，DOM 顺序可能变成 A C D E，而不是你想的“按时间序”。

这里的关键约束是：

• 同一个 Teleport vnode 内部，子节点顺序由 patch 算法保证
• 不同 Teleport 之间，仅由“挂载先后”决定，新挂载的总是 append 到末尾

所以最稳妥的做法是：只用一个 Teleport，把列表数据放进去，让 Vue 的 keyed diff 来管理顺序：

 复制代码

  
    

      {{ t.msg }}
    
  

这样无论增删，顺序都由数组 toasts 决定，符合直觉。

2.3 多个 Modal 叠加：z-index 还是 DOM 顺序？

另一个常见问题：业务中多个 Modal 同时打开，谁应该显示在上面？

答案分两层：

1. CSS 层面：默认共享同一个堆叠上下文，相同 z-index 时后渲染的 DOM 在上面（HTML 文档流的天然规则）。
2. Vue 层面：后挂载的 Teleport append 在后面。

这意味着，只要不手动指定 z-index，多 Modal 的层级会自然遵循“后开的盖在先开的上面”——这符合用户的使用直觉。

但如果你有多个独立编写的 ，它们的挂载顺序取决于父组件的 setup / 渲染顺序。同级兄弟之间没问题，跨组件则不可控。这种情况下，更好的方案是：

• 用 Pinia / 全局 store 维护一个 modalStack: ModalDescriptor[]
• 在一个集中的 里用 v-for 渲染整个栈

 复制代码

一个 Teleport + 一个数组 + 显式 z-index，比“散兵游勇式的多 Teleport”稳定得多。

2.4 嵌套 Teleport：可以但要谨慎

文档没有明说，但 Teleport 是支持嵌套的：

 复制代码
  
外层
  
    
内层
  

实际效果：外层 div 进入 #outer，内层 div 进入 #inner。逻辑上仍是父子关系（props/inject 都正常工作），DOM 上则是平行的两条传送线。

需要注意的是：嵌套场景在 SSR 下会被扁平化处理（参考 Vue Teleport 及其在 SSR 中的潜在问题 - CSDN），如果你做服务端渲染，最好避免这种结构。

三、源码视角：Teleport 是如何将节点“搬”过去的

要真正理解 disabled 切换、多目标渲染、defer 行为，最快的方式是看一眼 runtime-core 里的实现。下面是简化后的关键逻辑（基于 vuejs/core packages/runtime-core/src/components/Teleport.ts）。

3.1 Teleport 的 vnode 长这样

Teleport 不是普通组件，而是一个特殊 shapeFlag 的 vnode：

 复制代码// vnode 上挂着两个锚点
vnode.el         // 占位锚点（在 Teleport 原本位置的注释节点）
vnode.targetAnchor  // 目标容器内的锚点（决定 children 插入到哪儿）
vnode.target     // 解析后的目标 DOM 元素

两个锚点的设计是关键：

• el 留在源位置，方便 disabled 切回时把内容搬回来
• targetAnchor 在目标容器里，标记 Teleport 的内容应该插在哪里——这就是为什么多个 Teleport 指向同一目标时能够保持顺序

3.2 mount 阶段：disabled 的两条分支

 复制代码process(n1, n2, container, anchor, ...) {
  if (n1 == null) {
    // mount
    const placeholder = (n2.el = createComment(''))      // 占位锚点
    const mainAnchor = (n2.anchor = createComment(''))   // 主锚点
    insert(placeholder, container, anchor)
    insert(mainAnchor, container, anchor)    const target = (n2.target = resolveTarget(n2.props))
    const targetAnchor = (n2.targetAnchor = createText(''))
    if (target) insert(targetAnchor, target)    const mount = (container) => {
      mountChildren(n2.children, container, targetAnchor, ...)
    }    if (isTeleportDisabled(n2.props)) {
      mount(container)        // disabled：渲染在原位
    } else {
      mount(target)           // 正常：渲染到目标
    }
  }
  // ...
}

可以看到，mount 阶段就根据 disabled 决定子节点挂在 container（原位）还是 target（目标容器）。

3.3 update 阶段：disabled 切换 = move

更新分支里有这么一段（再次简化）：

 复制代码// update：disabled 状态变了
const wasDisabled = isTeleportDisabled(n1.props)
const isDisabled = isTeleportDisabled(n2.props)if (wasDisabled !== isDisabled) {
  if (isDisabled) {
    // 之前在 target，现在禁用 → 把内容搬回原位
    moveTeleport(n2, container, mainAnchor, internals, MoveType.TOGGLE)
  } else {
    // 之前在原位，现在启用 → 把内容搬到 target
    moveTeleport(n2, target, targetAnchor, internals, MoveType.TOGGLE)
  }
}

moveTeleport 的核心：

 复制代码function moveTeleport(vnode, container, anchor, internals, moveType) {
  // 遍历子节点 move 到新容器
  for (let i = 0; i < vnode.children.length; i++) {
    move(vnode.children[i], container, anchor, MoveType.REORDER)
  }
}

move 使用的是 parentNode.insertBefore(node, anchor)——浏览器原生 API。把已存在的 DOM 节点 insertBefore 到新位置，不会重新创建节点，状态全保留。这就是 disabled 切换平滑的真正原因。

3.4 多目标的顺序由谁保证

回到第二节的那个问题。当多个 Teleport 指向 #modals：

 复制代码// 每个 Teleport 在 mount 时执行
const targetAnchor = createText('')
insert(targetAnchor, target)  // 把自己的锚点 append 到目标
mountChildren(children, target, targetAnchor)

每个 Teleport 都往目标容器里 append 一个 targetAnchor，然后把 children 插在自己的锚点之前。锚点的 append 顺序 = Teleport 的 mount 顺序——这就是为什么“后挂载的在后面”。

理解这一层之后，你会知道：想精确控制顺序，要么合并成一个 Teleport，要么自己控制 children 的 v-for 数组。

四、SSR 场景：Teleport 真正的难点

4.1 服务端渲染时 Teleport 不会“传送”

Vue 官方 SSR 文档 里有一段关键说明：

服务端没有真实 DOM，document.querySelector('#modal-root') 在 Node 里无法运行。Vue 的处理方式是：将 Teleport 的内容单独输出到 ssr context，而不是塞进主 HTML 字符串中。

 复制代码const ctx = {}
const html = await renderToString(app, ctx)console.log(ctx.teleports)
// { '#teleported': '
teleported content
' }

需要由你把 ctx.teleports['#teleported'] 注入到最终 HTML 的对应位置。如果遗漏这一步，客户端水合时就会找不到节点 → hydration mismatch → 控制台一片红色错误。

4.2 hydration mismatch 的几个常见诱因

整理几个真实业务中高频出现的问题：

① 服务端和客户端的目标容器 ID 不一致

 复制代码

...

来源：Vue Teleport 及其在 SSR 中的潜在问题 - CSDN。结论：SSR 项目中，Teleport 的 to 应该是一个稳定字符串，而不是基于 window、isMobile 等浏览器态计算出的动态值。

② Teleport 直接传到 body

 复制代码...

Vue 官方文档 里明确建议：

中既有应用主内容，又混着 teleport 内容，水合时 Vue 找不到正确的起点。在 SSR 项目中，请使用专门的容器，比如

③ 客户端 onMounted 后才生成的内容

服务端渲染时输出 A，客户端 mount 后变成 B——必然 mismatch。这种情况要么：

• 客户端用 v-if="isMounted" 包裹（让服务端什么都不渲染）
• 用 Nuxt 的 包裹
• Vue 3.5+ 用 data-allow-mismatch 属性显式标记某些节点允许不一致

来源：Announcing Vue 3.5 - blog.vuejs.org。

4.3 SSR-friendly 的 Teleport 写法

综合下来，一个稳定的 SSR Teleport 模板大概是这样：

 复制代码

 复制代码
<body>
  <div id="app">div>
  <div id="modal-root">div>
body>

要点：

1. 目标容器是稳定的、应用之外的独立 DOM
2. SSR 阶段 disabled = true，内容留在组件树内输出
3. 客户端 mount 完成后切回 false，触发一次无副作用的 move

五、Vue 3.5+ 的 defer：解决“目标元素还没挂载”的老问题

5.1 一个老 Bug：目标在 Teleport 之后

3.5 之前，下面这段代码会报错：

 复制代码

报错信息是 Invalid Teleport target on mount。原因很直观：Vue 按模板顺序渲染，挂载到 Teleport 时 #late-target 还没出现在 DOM 中。

3.5 之前的常见绕法是：

• 将目标容器移到 index.html 里
• 或者用 nextTick + v-if 强行延后挂载

都不够优雅。

5.2 defer 的实现原理

Vue 3.5 的发布公告 中新增了 defer 属性：

 复制代码
  
传送内容

行为变化：Teleport 不在自己挂载的那一刻去找 target，而是等到当前渲染周期内的所有节点都挂载完成后，再去解析 target。文档原话：

源码里就是将 mount 推入 queuePostRenderEffect：

 复制代码const isTeleportDeferred = (props) => props && (props.defer || props.defer === '')if (isTeleportDeferred(n2.props)) {
  queuePostRenderEffect(() => {
    mountToTarget()
    n2.targetStart!.parentNode &&
      moveAnchors()
  }, parentSuspense)
} else {
  mountToTarget()
}

简单来说：defer 把 Teleport 的目标解析挂到了当前批次的“post effect”队列里——时机与 mounted 生命周期相同。

5.3 它可以做什么

最直接的两个场景：

① Teleport 到 Suspense 内部

3.5 之前，Teleport 不能指向 Suspense 内的容器（因为 Suspense 异步渲染）。3.5 之后：

 复制代码
  ...
  

来源：What's new in Vue 3.5? - blog.ninja-squad。

② 单文件组件内的“自包含 Teleport”

之前你必须在外部 HTML 里准备容器，现在可以直接写：

 复制代码

组件自带容器，不再依赖宿主页面提前布局。

5.4 它的边界

defer 不是万能延迟。文档明确：

如果你的目标元素是另一个组件异步加载几秒后才渲染的，defer 也无能为力——它只在同一个 tick 内等待。这种异步场景仍然需要使用老方案：v-if="targetReady" 配合事件通知。

六、将它们串起来：一个真实业务里的 Modal 系统

最后用一个较完整的例子收尾。它把上面几节都用上了：

 复制代码

 复制代码

这套写法的优势：

• 响应式断点：如有移动端 inline 需求，加一个 :disabled="isMobile || !isMounted" 即可
• 顺序可控：依赖 stack 数组而非多 Teleport
• z-index 显式：根据栈索引计算，不再依赖 DOM append 顺序的隐性约定
• SSR 友好：disabled="!isMounted" 让首次水合时内容留在原位
• 3.5 加成：defer 使 #modal-root 可以放在同一个组件中，去掉了对 index.html 的依赖

七、小结：被低估的三件事

回到标题，文档里被一笔带过的这几块，对应的关键点是：

更深一层，理解 targetAnchor 这个设计——Teleport 在源位置和目标容器各留一个锚点——能解释清楚为什么 disabled 切换不会丢状态、多目标顺序由挂载时机决定、defer 只是把锚点 insert 推进了 post effect。所有“看起来奇怪”的行为，都能在源码里找到一个具体的位置回答。

Teleport 不是一个高频编写的 API，但每次使用都有可能遇到某个文档没有展开讲解的细节。把这些细节理清楚，Modal、Toast、Tooltip、Drawer 这类组件就不会再有“为什么有时候 z-index 不对”或者“为什么 SSR 一开就白屏”的偶发问题。

参考资料

• Vue 官方文档 — Teleport
• Vue 官方文档 — Server-Side Rendering
• Announcing Vue 3.5 - blog.vuejs.org
• What's new in Vue 3.5? - blog.ninja-squad.com
• Vue 3 源码 — packages/runtime-core/src/components/Teleport.ts
• Teleport.ts coverage 视图
• Fix: Vue Teleport Not Rendering — fixdevs.com
• Vue Teleport 及其在 SSR 中的潜在问题 - CSDN
• SSR Is Not a Toggle — tiagobasilio.com
• Vue 3.5's — vuejstips.com