最常用且最稳妥的方案是将模态框用 Teleport 传送到 <body>。to="body" 是首选，因 <body> 页面加载即存在、合法且稳定；需包裹整个模态框结构并用 v-if 控制显隐，配合 position: fixed 定位，避免外层套 v-if、正确设置 z-index（建议 ≥1000）及处理焦点与滚动。

直接把模态框用 Teleport 传送到 <body> 就是最常用也最稳妥的“根节点级”方案。Vue 应用通常挂载在 <div id="app"> 下，而 <body> 是它最近的、稳定可用的公共父容器，能彻底避开 overflow、z-index 和定位上下文干扰。

明确目标位置：to="body" 是首选

Teleport 的 to 属性必须指向一个**已存在且可访问的 DOM 节点**。to="body" 是最直接的选择，因为 <body> 在页面加载时就存在，无需额外准备。

• 写法就是 <teleport to="body">...</teleport>，注意不是 to="document.body" 或 to="#app"
• 不要用 to="html" 或 to="document" —— 这些不是合法的 CSS 选择器，Teleport 会静默失败
• 如果项目有特殊结构（比如多应用共存），也可指定自定义容器，如 to="#modal-root"，但需确保该元素在 <body> 内提前声明

模态框组件里正确包裹内容

Teleport 只负责“搬运”，不控制显隐。模态框本身仍需用 v-if 或 v-show 控制是否渲染，否则即使传送到 body，也会占位或触发事件。

vue-composition-api-best-practices

Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。

下载

• 把整个模态框结构（遮罩层 + 内容区）包在 <teleport> 内，而不是只包其中一部分
• 确保内部样式使用 position: fixed 或 absolute，并配合 top/left/right/bottom 定位，避免依赖父容器流式布局
• 例如：<teleport to="body"><div v-if="open" class="modal-overlay">...</div></teleport>

避免常见陷阱

传送成功不等于表现正常。几个关键细节决定最终效果是否可靠：

立即学习“前端免费学习笔记（深入）”；

• 不要在 Teleport 外层套 v-if：如果写成 <div v-if="open"><teleport>...</teleport></div>，会导致 Teleport 实例被销毁重建，状态丢失、动画中断
• z-index 需全局统筹：传送到 body 后，模态框脱离原有层级，它的 z-index 要比所有其他 body 子元素高（建议设为 1000+）
• 焦点与可访问性不能丢：模态框打开后应自动聚焦首个可交互元素，并禁用背后内容滚动（可通过 document.body.style.overflow = 'hidden' 实现）

进阶：支持多个模态框叠加

单个 Teleport 不限制内容数量，多个模态框可共用同一个 to="body" 目标，Vue 会按顺序追加到 <body> 末尾。

• 每个模态框保持独立的 v-if 控制，互不影响
• 叠加时靠 z-index 逐级递增，例如第一个 1000，第二个 1001，避免遮挡逻辑混乱
• 不需要为每个模态框新建 Teleport 实例，复用即可