Vue3 的“模块语法革命”如果要用一句话概括最直观的就是“告别多根节点包裹拥抱 Fragments”。熟悉 Vue2 的朋友应该都有过这种经历写一个组件时只要模板里出现了两个平级的元素编译器立刻在控制台抛一个警告要求你“The template root requires exactly one element”然后你不得不额外包一层div。这一层 div 看似无所谓但真正做复杂业务的时候它会把布局层级硬生生地拉深一层会破坏 flex/grid 的子项关系还会让语义化标签变得不伦不类。Vue3 引入了 Fragments多根组件从“违规”变成“合法”这不仅仅是语法上少包一个标签而是对运行时渲染模型的一次调整。这篇文章我不打算只停留在“怎么用”的层面更多会聊聊 Vue3 为什么要这么设计、底层 VNode 和 patchFlag 发生了哪些变化以及从 Vue2 项目迁移时到底该怎么处理多根组件。无论你是刚从 Vue2 转到 Vue3还是正在封装基础组件库里面应该都有一些可以直接抄走的经验。1. 告别包裹层的真实价值不止是少写一个 div1.1 Vue2 时代那根被迫存在的“毒 div”在 Vue2 中每个组件的 template 最终都会编译成一个 render 函数这个 render 函数必须返回一个虚拟节点VNode并且只能返回一个。Vue 实例挂载之后会把这个 VNode 渲染成真实的 DOM 节点作为组件的根元素绑定到组件实例上。所以只要你写了两个平级节点Vue 就不知道到底该把哪个当作根。解决办法只有一个在外面再套一层。这个包裹层在大多数场景里只是个无意义的空壳但副作用却很实在。最常见的是列表和表格场景。比如你要封装一组li在 Vue2 里必须写成divli.../lili.../li/div但这样的结构放在ul里明显是无效 HTML。又比如要给一个表格加多个tr或td外层包裹 div 会导致浏览器解析时自动把它挪出来页面直接错位。为了规避这种情况很多组件库会选择使用render函数 函数式组件来绕过单根限制但写法非常别扭。1.2 多根节点对布局与样式的解放Vue3 放开多根节点限制之后受益最大的其实是 CSS 布局。想象一下你要做一行 flex 布局里面由两个组件组成一个文字块、一个按钮。在 Vue2 中你必须给这两个组件分别套一个不会影响 flex 的包裹层如果包裹层是 div它就成了 flex 容器里的一个子项导致你原来的两个子项不得不包在一个 div 里再去设置display: contents或者调整选择器。很多人写 Vue2 组件库时为了处理这种问题会特意让根节点继承外层的 class或者使用$attrs透传非常麻烦。有了 Fragments组件的多个子元素可以直接作为父级 flex/grid 容器的子项样式关系和原生写法完全一致。这在开发抽屉、弹窗、表单行、导航菜单这类组件时尤其舒服不需要再额外包一层无意义的元素。另一个容易被忽视的好处是语义化与无障碍。多根组件可以直接输出dt dd组合可以输出thead tbody也可以输出一组option不再强行插入一个 div 去破坏文档结构对屏幕阅读器也更友好。1.3 Fragments 并不仅是“模板层面去壳”Fragments 并不是简单地把模板里的多个根节点“拼接在一起”然后渲染时去掉包裹层。它是在虚拟 DOM 层面定义了一种特殊类型的节点叫 Fragment 节点。Fragment 节点本身不产生任何真实 DOM 元素它只是一个容器用来存放一组子节点。渲染器在看到 Fragment 节点时会直接遍历它的 children 并把它们分别挂载到父级容器里相当于一个透明的占位。这种设计的意义在于组件仍然是一个完整的组件有自己的生命周期、依赖注入和更新边界只是它的“根”不再是一个元素而是一个碎片集合。因此渲染器必须能处理这个碎片集合。Vue3 的源码里为这个碎片集合专门设计了 patch 逻辑和普通元素节点、文本节点、组件节点区别开。这可不是在编译器里偷偷加一个数组那么简单。1.4 什么时候该用多根什么时候不该用多根虽好但不能无脑用。我的经验是如果组件输出的是单一段落、单张卡片、单个按钮老老实实保持单根更利于复用。因为单根组件天然支持外部传入 class、style、事件监听器$attrs会自动继承到根元素上。而多根组件的class和style无法自动处理因为渲染器不知道该把它们放到哪个根上需要你自己在组件内部手动绑定。适合用多根的场景大概是这几类需要返回同一层级的多个列表项、单元格、行元素不想因为额外包裹层破坏 flex/grid/绝对定位布局需要保证 HTML 语义正确比如dl中的一组dt/dd想要把一个模块拆成多个并列片段但不想增加真实 DOM 层级。而像按钮、输入框、卡片这种“独立组件”单根依然是默认选择。Fragments 是工具不是银弹凡是把多根组件当普通单根组件去外部套 class 的很容易在样式透传上踩坑。2. 从 VNode 到 Fragment理解 Vue3 的底层编译与渲染2.1 单根限制的源头VNode 的“一个萝卜一个坑”为什么 Vue2 如此执着于单根因为它的渲染和更新模型是围绕“组件等于一个 VNode 树”设计的。每个组件实例在挂载时需要知道自己的宿主元素在哪里。更新时diff 算法从组件根 VNode 开始和旧 VNode 进行比对然后递归更新整棵树。如果根 VNode 下面还有多个兄弟节点这个树结构就变成了一个森林组件的“唯一根”概念就站不住脚。Vue3 则把“组件挂载”和“组件根的渲染”分离了。组件实例在挂载时不需要直接对应一个 DOM 元素而是对应一个 VNode。这个 VNode 的类型可以是元素、组件、文本、注释也可以是 Fragment。于是碎片森林也能作为一个整体被组件承接组件树从“单根树”变成了“可以是多根树”。从数据结构上看单根约束更像是一个历史包袱Vue3 只是把这个包袱从运行时拿掉了。2.2 多根模板编译后的 render 函数长什么样如果你把下面的 Vue3 组件模板template h1标题/h1 p描述/p /template交给编译器处理大概会得到类似这样的 render 函数import { createElementBlock, openBlock } from vue export function render(_ctx, _cache) { return ( openBlock(), createElementBlock( Fragment, // 特殊类型标记 null, [ createElementVNode(h1, null, 标题, 1 /* TEXT */), createElementVNode(p, null, 描述, 1 /* TEXT */) ], 64 /* STABLE_FRAGMENT */ ) ) }关键就在createElementBlock(Fragment, null, [...], 64)。这里的createElementBlock是在构建优化后的编译器输出中经常出现的函数它本质上会调用createVNode但额外会开启一个块Block。Fragment并不是一个真实的 HTML 标签而是一个特殊的 VNode type 值在 Vue3 内部通常是一个 Symbol。因为 Symbol 不可能和 HTML tag 重名所以渲染器可以安全地识别出这是一个 Fragment 节点而不是真实的元素节点。这里有个小细节如果你用vue/compiler-sfc的compileTemplate去手动编译一个多根模板你会发现返回的 AST 根节点实际上是一个名为Fragment的模拟根节点所有顶层真实节点都作为它的 children。也就是说单根限制在编译器层面被打破了但开发者仍然不会直接接触 Fragment。2.3 Fragment 的三种 patchFlagSTABLE / KEYED / UNKEYEDVue3 在 diff 一个 Fragment 节点时会根据子节点的稳定性选择不同的更新策略这部分体现在 patchFlag 上。我查阅官方源码时发现常用的有三位STABLE_FRAGMENT (64)表示 Fragment 的子节点是静态稳定的没有使用v-for也不存在需要按 key 重排的情况。更新时 Vue 会尽量复用旧节点不做无谓的移动。KEYED_FRAGMENT (128)表示子节点是通过v-for生成并且提供了 key。diff 时会按照 key 进行快速匹配和移动这是最高效的列表更新方式。UNKEYED_FRAGMENT (256)表示子节点是动态生成的但没有提供 key。diff 时只能按索引暴力对比性能较差而且可能出现状态错位。模板编译器会自动生成正确的 patchFlag。你写一个v-for列表如果项目里写了:key编译结果就是KEYED_FRAGMENT如果忘记写 key就会是UNKEYED_FRAGMENT。这个标记对多根 Fragment 同样适用。你可以在模板里用v-for直接循环输出很多根节点编译后的 Fragment 会保存列表更新所必需的动态结构。理解这三种 patchFlag 的价值在于你不需要刻意优化但要知道为什么多根组件有时比单根包裹反而更快。单根组件列表更新时diff 器要先经过那一层 div再进入列表多根组件的 Fragment 直接让列表项成为兄弟节点少了一层递归比较。加上KEYED_FRAGMENT的存在Vue 甚至可以直接通过 key 定位需要更新的节点而不用每次都从头比对子树。2.4 为什么说“多根优化”是对 DOM diff 的一次成本减负讨论 Vue3 性能时很多人只盯着虚拟 DOM 的对比算法却忽略了减少真实 DOM 节点数量本身就是最快的优化。多根组件没有包裹层所以整个组件渲染后的 DOM 树层级更浅、节点更少。diff 过程中需要遍历的子树更小浏览器在创建、插入、删除节点时操作也更少。举个例子一个卡片组件如果 Vue2 里面包了一层 div底层传给它的插槽内容会全部成为这个 div 的子树哪怕插槽内容完全没变diff 也要从那个 div 开始逐层检查。而 Vue3 的多根组件可以做到“插槽内容就是组件的兄弟节点”从结构上就省掉了一层不必要的容器。这不是微优化在大量列表渲染、频繁增删操作的场景下能明显感受到帧率的提升。当然有人会说多根组件会让组件树变得混乱因为组件根不是一个节点使用 devtools 时树结构看起来不如单根直观。实际上Vue DevTools 已经针对 Fragment 做了展示组件树中会显示“Fragment”这个虚拟节点查看起来并不会丢失信息。只要不是在transition或某些特殊 API 的场景里强行使用多根收益通常是正向的。3. 实战上手从模板到 render 函数全面拥抱多根3.1 最简单的多根组件模板写法在 Vue3 的单文件组件里直接写平级标签就是多根组件。不需要任何配置也不需要额外 import 什么。!-- 多根Demo.vue -- template h2 classtitle标题区域/h2 p classdesc一段描述文字/p /template编译后这个组件会被自动视为一个 Fragment 渲染。如果你在父组件里引用它template section MultiRootComponent classparent-class / /section /template注意classparent-class不会被自动作用到任何子元素上。因为在多根组件中外部传入的 class、style、listeners 没有明确的单一目标。这一点和单根组件完全相反。如果确实要让外部 class 作用到某个节点上你可以通过$attrs手动绑定template h2 v-bind$attrs标题/h2 p描述/p /template这样父组件传入的非 prop 属性会落到 h2 上。我个人推荐的做法是多根组件尽量避免依赖外部 class 透传业务所需的样式要么自己写死要么通过 prop 传递否则很容易出现“类名没生效”的困扰。3.2 给多根节点加上 key避免 diff 阶段的坑多根组件如果只是静态模板基本不需要关心 key。但一旦根节点带有v-if、v-for或者使用动态组件切换就应该谨慎处理 key 的问题。尤其是同一级有多个根节点并且它们会随着条件变化而互相替换场景。比如这个模板template div v-ifloading加载中/div div v-else-iferror加载失败/div div v-else内容区域/div /template上面三个 div 实际上构成一个 Fragment 下的多个条件分支但同一时刻只会有一个渲染。Vue3 的 diff 机制会把它们当作多个子节点处理如果这些节点没有 key切换时可能会复用错误的 DOM导致子组件状态残留。解决办法很简单给每个分支加上一个稳定的 key。template div v-ifloading keyloading加载中/div div v-else-iferror keyerror加载失败/div div v-else keycontent内容区域/div /template加了 key 后diff 才会把它们识别为完全不同的节点避免跨分支复用。同理如果你用v-for渲染多个根节点必须给每一项加:key。很多初学者在多根组件上忘记写 key导致列表删除或排序时出现状态错乱这不是 Fragments 的问题而是 diff 需要 key 来建立新老节点映射关系。3.3 在 render 函数 / JSX 中显式使用 Fragment模板编译器会自动生成 Fragment但如果你直接写 render 函数或 JSX就需要自己处理多根返回值。在 Vue3 中render 函数可以直接返回一个子节点数组而不需要包裹任何层。例如import { h } from vue export default { render() { return [ h(h2, 标题), h(p, 描述) ] } }这个数组会被 Vue 自动当作 Fragment 处理。如果你想显式地突出 Fragment也可以直接引入Fragment作为 VNode 类型import { h, Fragment } from vue export default { render() { return h(Fragment, null, [ h(h2, 标题), h(p, 描述) ]) } }在 JSX 中多根也非常直观const MultiRoot () ( h2标题/h2 p描述/p / )这里的/就是 React 风格的 Fragment 写法。Vue 的 JSX 插件会把它编译成Fragment节点。但要注意一点render 函数返回数组和模板多根并不完全等价。模板多根时编译器可以精确生成静态标记比如自动判断 Fragment 是 stable、keyed 还是 unkeyed而手写 render 返回数组时编译器不会帮你生成优化标记你需要自己在 VNode 上传递 patchFlag 才能达到同等性能。不过大多数业务场景下手写 render 的开销差异可以忽略。3.4 多根组件的边界场景Teleport、Suspense、组件库封装Fragments 在特定内置组件里也有自己的位置。比如Teleport以前要求被传送的内容必须有单根现在它也能接受多根内容。渲染器会把 Fragment 里的多个子节点直接挂载到目标容器不会额外产生一个空壳。这在做全局弹窗、移动端出入口时很实用。Suspense的插槽也可以返回多根内容异步组件的加载状态和默认内容在结构上更灵活。不过实际经验是Suspense和Transition一起用时多根组件容易产生一些边界警告尤其是 Transition 期望只有一个直接子元素。因此如果需要做过渡动画尽量保持单根。组件库封装是最能体现 Fragments 价值的地方。比如你要做一组表单控件包含 label 和 input不想额外包一层 div 破坏网格布局。你可以这样设计template label :forid v-bind$attrs{{ label }}/label input :idid typetext / /template在单根限制下你不得不包一层div classfield-item然后为了对齐还要去设置该 div 的 display。有了多根label 和 input 可以直接作为网格容器的两个单元格。这在开发后台管理系统时能省掉大量无意义的 flex 布局容器。4. 从 Vue2 项目迁移时的多根适配指南4.1 迁移前先识别哪些组件是被迫包裹的如果你正在把一个老项目从 Vue2 迁移到 Vue3直接全局搜索模板里那些“明显为了消除警告而加的包裹层”是个好入口。怎么判断一个 div 是包裹层而不是有意义的布局层我的经验是看它的 class 或 style。如果这个 div 没有任何 class、没有任何事件、也没有绑定样式仅仅是为了裹住里面的两个子节点那它大概率就是被迫的包裹层。比如这样template div div classtitle标题/div div classcontent内容/div /div /template这个外层 div 多半可以删掉。删掉后组件变成多根内部样式不会受影响。但要注意如果外面的父容器通过该组件的根元素选择器来控制间距、对齐或者 hover 高亮删掉后这些规则就会失效。迁移前最好先看 CSS 里有没有类似.xxx div的选择器。在高频组件中删除包裹层不仅减少了 DOM 节点还能简化组件树。我曾把一个列表项组件从单根 div 改为多根配合父级的display: contents使用渲染性能有肉眼可见的提升尤其是在 1000 条数据的页面上。4.2 自动化迁移工具能帮你做什么Vue3 官方提供了一个迁移构建版本可以帮你检查 Vue2 特有的写法但真正起大作用的是社区整理的一套 codemod 工具专门针对模板代码做自动替换。不过据我所知自动工具对“多根包裹”的处理还不够聪明无法准确判断哪些 div 是单纯为了满足单根限制哪些是真正有样式的。所以自动化工具通常只能帮你把语法层面的错误修掉比如$children、$on、$once、filter删除等多根包裹得靠人肉识别。我的建议是先跑一遍迁移工具让项目能在 Vue3 下编译运行不要急着把所有外层 div 删掉。等编译通过、功能稳定后再挑选核心组件逐个手工去除包裹层。这样风险最小。如果你一开始就大范围改动 DOM 结构很容易因为某处样式依赖根节点而出问题排查起来特别痛苦。4.3 多根组件带来的常见警告及处理速查表从 Vue2 转来的人经常会在控制台看到一些以前没见过的警告下面是几个高频问题和我自己的处理方式。警告/报错信息可能原因处理方案Component inside Transition renders non-element root nodeTransition组件要求直接子组件必须是单根元素但你的子组件是多根组件给该子组件最外层手动包一个单根容器或者避免在多根组件上使用 TransitionFragment is not a real DOM node相关调试信息多根组件作为某个 API 的挂载点比如app.mount()返回的根组件不能有多个根根组件app.mount的对象尽量保持单根页面级组件多根会导致挂载行为异常列表更新后 DOM 状态错乱、输入框值串位Fragment 子节点使用v-for但没有提供 key或条件分支没有稳定 key给所有动态根节点添加稳定的唯一 key在第三方 UI 库中传入多根组件后样式失效多根组件不支持自动继承 class外部传入的样式没有落到指定节点在组件内部用$attrs手动绑定到目标节点或改用 prop 传参这个速查表是我在维护内部组件库时总结出来的频率最高的其实是 Transition 和输入框串位这两个。如果你要封装可复用组件建议在所有涉及动画的组件里明确单根约定避免使用者传入多根组件导致警告。4.4 我自己踩过的三个坑第一个坑是“多根组件不能作为根组件直接 mount”。在 main.js 里createApp(App).mount(#app)时App 的模板如果出现多个根节点挂载会报错因为 Vue 需要把实例挂载到一个明确的根 DOM 元素上。解决方法是 App 模板保持一个单根比如一个div idapp。多根限制只是针对子组件不是针对整个应用。第二个坑是响应式依赖收集在 Fragment 中比预想更复杂。当一个多根组件的某个根节点被v-if切换掉时Vue 会更新 Fragment 的子节点数组。如果子节点数组的元素顺序发生改变没有 key 的情况下旧节点的响应式数据可能绑定到错误的新节点上。表现就是“明明切走了 loading但 loading 的动画还在影响其他区域”。我后来强制所有条件根节点都加 key这个问题就消失了。第三个坑是样式优先级的隐形改变。删除包裹层之后原先依靠父标签之间相邻选择器的样式可能失效比如div div的间距。多根组件会把两个根节点变成兄弟节点间距选择器需要调整成:first-child或使用gap。这种问题在视觉上很微妙可能只是少了 8px 间距但原因极其隐蔽。如果你的多根组件在删除 div 后布局“莫名塌了”先去看相邻兄弟选择器。最后分享一点个人体会。在 Vue3 里多根组件已经是非常成熟稳定的能力不用再像 Vue2 那样想方设法用函数式组件去伪造 Fragment。但“能用多根”不等于“处处都要多根”。我做项目时的原则很简单单根组件是默认除非遇到列表项、表单控件、布局碎片这些真实第三方场景才考虑改成多根。这样既能享受 Fragments 带来的结构自由又不会陷入 class 透传和动画兼容的麻烦。如果你正在写基础组件库建议从最容易被 DOM 层级拖累的布局类组件开始尝试比如行的子项、表单的 labelinput 结构、表格的单元格组合。把包裹层删掉重新跑一遍页面你会明显感知到样式控制变得顺手很多。这就是 Vue3 模板语法革命里最实在的一部分收益。