给 Vue 组件挂上 vapor 之后:先崩的四个运行时约定
本文基于 Vue core 的 CHANGELOG(minor 分支):
版本坐标
Vapor Mode 仍在 RC 阶段:3.6.0-rc.16 于 2026-11-20 发布,此前 rc.15 为 2026-11-12,rc.14 2026-10-30,rc.13 2026-10-23,rc.12 2026-10-16,rc.11 2026-10-10,rc.10 2026-09-30;改动最大的 rc.2 是 2026-07-22。同日发布的稳定线是 3.5.46。也就是说,这是一条需要单独评估的升级路径,不能把 3.6 当作 3.5 的常规小版本。
入口有三种等价写法:、、``。纯 Vapor 应用用 createVaporApp():
import { createVaporApp } from 'vue'
import App from './App.vue'
createVaporApp(App).mount('#app')
在 createApp() 创建的 VDOM 应用里使用 Vapor 组件,需要安装 vaporInteropPlugin:
import { createApp, vaporInteropPlugin } from 'vue'
createApp(App).use(vaporInteropPlugin).mount('#app')
反过来,Vapor 应用实例也可以安装 vaporInteropPlugin,以便在内部使用 VDOM 组件,但这会把 VDOM 运行时拉进来,抵消小包体收益。用渲染函数或 JSX 写的组件仍然是 VDOM 组件,放进 Vapor 应用同样需要 interop。官方建议在应用里划出明确区域,一部分走一种渲染模式,尽量避免混合嵌套。
下面四条是给组件加上 vapor 标记后最先暴露的断点:它们不涉及性能,全都是运行时约定上的差异。
一、getCurrentInstance() 在 Vapor 组件里返回 null
发生问题的情况:大量 composable 和组件库靠 getCurrentInstance() 拿当前实例,再读 instance.proxy、instance.appContext、instance.props,或者拿实例去挂 provide/inject 之外的上下文。Vapor 组件的公共实例 proxy 本身就是不存在的,这类调用会在 Vapor 组件里静默拿到 null,随后在 .proxy 或 .appContext 上抛错,或者更糟——走进一条 if (instance) 的兜底分支,行为悄悄变了。
修改方法:把依赖实例的逻辑从组件内部剥离。能通过 provide/inject、props、显式传参拿到的上下文,就不要从实例上摸。确实需要实例的第三方组件库,保持它是 VDOM 组件,通过 vaporInteropPlugin 在边界处使用,不要硬塞进 Vapor 组件里。这一条也直接决定了迁移范围:依赖面越深的老组件,越不适合第一批迁移。
二、slots.default() 不是无副作用的 dry run
发生问题的情况:判断「有没有传内容」时,常见写法是先调用一次插槽再判断结果:
const content = slots.default?.()
const showFallback = !content
在 Vapor 里,调用 slots.default() 会真的执行插槽的渲染逻辑:创建 Block 与 DOM 节点、注册响应式 effect,在 hydration 阶段还会占用已有的 SSR DOM。你以为在探测,其实已经把插槽渲染了一遍;后续模板再渲染一次,就会出现节点重复、SSR DOM 被提前取走、effect 重复注册这类问题。
修改方法:不要调用插槽来检查输出,把渲染交给模板:
有没有内容、要不要兜底,由模板里的 `` 和它的 fallback 内容表达。另外,beta.1 的说明提到 Vapor slots 不能在 VDOM 组件里用 slots.default() 渲染,必须用 renderSlot。
三、自定义指令换了一套接口
发生问题的情况:VDOM 的指令接口是 (el, binding, vnode, prevVnode),binding 是个对象,.value、.arg、.modifiers 都在上面;卸载清理走 unmounted 钩子。这套直接搬到 Vapor 组件上,参数位置和语义全都不对。
修改方法:Vapor 的指令签名是:
type VaporDirective = (
node: Element | VaporComponentInstance,
value?: () => any,
argument?: string,
modifiers?: DirectiveModifiers,
) => (() => void) | void
第二个参数 value 是一个响应式 getter,调用它才拿到绑定值,因此不能再按静态值处理。需要响应式副作用时用 watchEffect(),它会在组件卸载时自动释放;指令也可以返回一个清理函数:
const MyDirective = (el, source) => {
watchEffect(() => { el.textContent = source() })
return () => console.log('cleanup')
}
迁移时逐个核对指令:取值改成 value() 调用,副作用从 mounted/updated 钩子改到 watchEffect,手动清理逻辑收进返回值。
四、事件委托从默认改成 opt-in
发生问题的情况:在 rc.2 之前,Vapor 会把支持的事件自动委托到 document。这与 VDOM 模式和原生 DOM 行为不一致:祖先调用 stopPropagation() 时,事件到不了 document,子元素的 handler 就不会执行。反过来,依赖「默认就有委托」写的代码,在升级后也会发现委托不再生效。
修改方法:从 rc.2 起,DOM 事件监听默认直接绑定到元素上,与标准 Vue 和原生 DOM 行为一致。委托变成显式优化,用 Vapor 专有的 .delegate 修饰符开启:
compilerOptions.eventDelegation 已被移除,现有配置里要删掉这项,需要委托的监听器逐个加 .delegate。
注意 .delegate 只是把老的限制重新引回来:委托后的 handler 由 document 上的单个监听器沿事件路径匹配调用,因此祖先一旦调用 stopPropagation(),事件到不了 document,委托的 handler 仍然不会触发。此外下面三种写法会绕过委托、直接绑到元素上:、、``。
Vapor 不支持的部分
- Options API
app.config.globalProperties@vue:xxx逐元素生命周期事件v-memo- 组件模板 ref 不暴露
$el、$props、$attrs、$slots、$refs
这份清单基本划定了「不能迁移」的边界。依赖全局属性挂工具的代码、依赖 @vue:mounted 之类逐元素钩子的代码、依赖组件 ref 反向读 $attrs/$slots 的代码,都需要先改造,再考虑 vapor 标记。
官方对行为一致性的表述是:Vapor 尽量匹配 VDOM 行为,但两种渲染模式根本不同,边缘场景仍可能有细微不一致,一般不算 breaking change,除非该行为此前已被文档化。rc.15 的修复集中在 compiler-vapor / runtime-vapor / reactivity,涉及 KeepAlive 分支、slot 边界、hydration、HMR 等,也说明这些边角仍在收敛。
另外,3.6 对 @vue/reactivity 做了基于 alien-signals 的重构,官方称显著提升响应式系统的性能与内存占用。这是内部改动,ref/reactive/computed/watch 的 API 不变,所有 Vue 应用升级即可获得,与是否使用 Vapor 无关。
何时局部上 Vapor,何时别动
在以下情况,值得在局部上 Vapor:应用里存在边界清晰、依赖少、结构稳定的叶子区域,比如纯展示的列表项、图标与骨架屏、独立的 widget;这些组件不碰 getCurrentInstance(),不用 slots.default() 做内容判断,自定义指令不多且愿意按新接口重写;同时应用本体继续跑 VDOM,用 vaporInteropPlugin 在边界处衔接。
不要改动的情况:组件库和核心 composable 依赖实例 proxy;组件大量通过 slots.default() 检查内容或做包装;自定义指令是主要扩展手段;依赖 app.config.globalProperties、@vue:xxx、v-memo 或从组件 ref 读 $attrs/$slots;以及应用需要在 Vapor 与 VDOM 之间频繁互相嵌套——那会把 VDOM 运行时重新拉进来,包体收益也就没了。3.6 还在 RC,3.5.46 才是稳定线,迁移节奏应当按这个坐标安排。