Vue 3 正式发布已经这么久了但从 Vue 2 迁过去并不是换个语法那么简单。我见过太多人学了几天 Composition API 就开始写项目结果响应式数据莫名其妙丢失、组件通信改得云里雾里、项目跑起来一堆坑。这篇 vue3 知识汇总我不打算给你念一遍官方文档而是从实际开发中最容易困惑的几个点上做一次系统的梳理和避坑总结。先说清楚这篇内容适合谁正在从 Vue 2 往 Vue 3 过渡的开发者已经用 Vue 3 写过一段时间但总觉得理解不够系统的初中级前端以及准备面试但对组合式 API 理解停留在一个是 data一个是 ref的朋友。不管你处在哪个阶段这轮汇总都会帮你把 Vue 3 的零散知识点穿成一条线。1. 从 Options 到 CompositionVue 3 的换写法背后到底换了什么1.1 响应式底层的原理级升级而不是表面 API 变动很多人把 Vue 3 当作Vue 2 加了个 setup 函数这是最危险的理解。Vue 3 的整个响应式系统从底层换了一遍Vue 2 的响应式基于Object.defineProperty对对象属性做递归拦截Vue 3 则改用Proxy做对象级拦截。这个变化直接带来三个实际效果第一新增属性本身具备响应式。Vue 2 里必须用Vue.set或者this.$set处理动态新增的 key否则不触发更新。写惯了 Vue 2 的人很容易在 Vue 3 里下意识找$set其实根本不用直接state.newKey value就是响应式的。这一点在新手刚迁移时尤其容易踩心里还停留在对象的属性必须在初始化时就声明好这个惯性里。第二数组的更新拦截不再靠重写方法 索引检测。Vue 2 中直接通过索引修改数组如arr[0] xxx基本可以确定不会触发视图更新Vue 3 里这一限制消失了。很多做列表拖拽、表格单元格直接编辑的场景迁移过来体验会亮眼很多。第三Map、Set、WeakMap 这类数据类型可以直接拥有响应式能力这在 Vue 2 时代基本是做不了的。Vue 3 的reactive内部对集合类型也做了专门的处理能拦截get、has这类操作所以当业务里需要维护一个Map做缓存、权限映射、字典表时不再需要绕路转成普通对象。底层变化带来的连锁反应是Composition API 不是凭空发明的新概念而是把响应式能力和数据 行为的聚合能力解耦开所以 Vue 3 才能拆出独立的vue/reactivity包。哪怕你不用 Vue 框架单独拿这个包在 Node 或原生小程序里做响应式状态管理也完全可行。理解了这一层你就明白了 Vue 3 这波改革真正的大方向是响应式独立化。1.2 setup 里做组合Options 里做理解——不是非黑即白接下来必须聊setup。这是个函数它有两个关键点很多人容易忽略执行时机和 this 的不可用性。执行时机上setup在beforeCreate之前执行。这意味着你在setup里做this.$refs.xxx是拿不到的组件实例在setup执行阶段初始化做得很少data、computed、methods都还没挂到实例上。所以文档里会强调在 setup 中this 无法访问组件实例不是语法层面的限制而是执行时序导致的天然隔离。果然有不少人在setup里写const vm this然后一运行就是 undefined就是这个原因。那 Options API 是否就没用了我在实际项目里的做法是两者保留意图复杂的业务逻辑用 Composition API 聚合组件的 props、emit 声明和对外的可读骨架继续用 Options 的一部分能力比如props用defineProps在script setup里声明但name属性我仍然用 Options 风格的export default { name: xxx }来声明。Vue 3 官方也从没说过 Options API 被移除它就一直在那写Options写习惯了的人可以先在script setup的顶层保留 Options 字段再逐步往组合式逻辑迁移每个组件内部不强求风格统一这个对团队落地尤其重要。1.3 逻辑复用阶段的改变mixin 被 minimax 式的组合取代Vue 2 时代做逻辑复用基本靠 mixin。但 mixin 有几个体验很差的问题命名冲突不可控多个 mixin 里都定义了getUserInfo后加载的覆盖前者、隐式依赖严重mixin 内部依赖组件里的data维护时根本不知道这个字段是哪里来的、来源不清晰模板里一个变量背后可能是组件自身数据也可能是第三个 mixin 的 data。Vue 3 的组合式函数把这个问题改造成接近于函数式装配的模式。你可以把一组逻辑封装成一个普通的函数函数内部自行维护 ref/reactive 状态并返回需要暴露的对象// useUserInfo.ts import { ref, onMounted } from vue export function useUserInfo() { const userInfo ref(null) const loading ref(false) async function fetchUserInfo(id) { loading.value true try { const res await fetch(/api/user/${id}) userInfo.value await res.json() } finally { loading.value false } } onMounted(() { fetchUserInfo(1) }) return { userInfo, loading, fetchUserInfo } }之后在组件里用的时候我看中的是想暴露给模板的变量必须解构后显式返回这个取舍。你不再面临 mixin 那种全字段对组件开放的尴尬。调用方明确可读script setup langts import { useUserInfo } from /composables/useUserInfo const { userInfo, loading } useUserInfo() /script这种模式清晰到什么程度你一眼就知道userInfo是useUserInfo的产物后面的数据流动路径是确定的。不过注意组合式函数内部如果你统一用ref包裹状态返回值的解构不会破坏响应式因为ref本身就是把值包进对象里解构得到的ref对象依旧有效。这一点和reactive直解构的响应式丢失形成鲜明对比稍后单独细讲。2. ref 和 reactive 选择的实战决策以及响应式丢失的几种场景2.1 它是值它是对象——两个 API 的边界到底在哪里ref和reactive是最容易让新手纠结的组合。我的判断标准非常简单能展示到模板或者需要在函数间作为值传递的优先 ref一整坨有一定结构、未来会被整体替换的纯数据用 reactive 更方便但千万别不加思考直接 reactive 一把梭。先看ref的本质。源码里ref接收一个任意值如果是对象内部会调用reactive来包装这个对象并把最终结果挂到ref.value上。所以你可以理解成ref是给任意值套了一层可解包的响应式容器它的核心特征在于value这个访问路径是固定的传递和赋值都不会丢失响应式。reactive的目标是对象本身它直接使用Proxy包装目标对象访问时无需.value写起来更接近 Vue 2 的 data 手感。但它的软肋在解构和重新整体赋值上。这里列一张我在代码评审时反复用的选型对照场景推荐方案理由计数器、开关、输入框绑定值ref简单值.value 明确且不易误用表单数据整体对象字段多reactive模板里不用四处写.value开发体验顺列表数组会做整体替换或过滤操作ref 包数组整体赋值只需list.value newArr不会丢响应式从后端拉取的一坨嵌套对象reactive修改深层字段很自然模板访问直观需要在多个函数间传来传去或对外暴露ref引用路径稳定不依赖调用方是否解构正确对象里的某个字段要单独拿出来用reactive toRefs解构过程保留响应式字段级使用这张表不是死规则。我的核心思路是尽量在一个组件里选定一个主风格减少团队心智负担。要么全是ref除了极少数 reactive 形态的对象要么明确定义什么场景才用reactive。最怕的是同一个组件里一会儿ref一会儿reactive模板里一会儿.value一会儿不带让人晕头转向。2.2 解构丢失响应式最容易偷走项目正确性的元凶响应式丢失最常见的一幕是这样的const state reactive({ user: A同学, age: 18 }) const { user, age } stateuser和age变成两个普通的字符串和数字之后修改它们不会触发任何视图更新。原因很本质reactive的响应式依赖Proxy对原对象的代理当你把原始值从对象里解构出来得到的已经不是原对象的属性访问了而是一份拷贝Proxy的拦截逻辑自然管不到。如果你确实想解构正确的做法是toRefsconst state reactive({ user: A同学, age: 18 }) const { user, age } toRefs(state)toRefs会把对象的每个属性转换成独立的ref且这些ref和原state属性保持连接修改user.value或age.value都能触发原状态的响应。适合在把 reactive 数据传递给子组件、拆分给多个组合式函数时使用。我不止一次在评审里看到这种代码const { userInfo } storeToRefs(store) // 结果子组件里拿到的 userInfo 是个 ref但写模板时写死了 {{ userInfo.name }}这是另一个高频误区storeToRefs返回的每个属性本身是ref模板中自动解包只在顶层生效{{ userInfo.name }}如果userInfo是 ref模板会先解出userInfo的值再去取name而如果userInfo本身存的又是一个对象那链式解包其实没问题。真正有风险的是把返回的 ref 再解构后又赋给别的变量绕两圈之后响应式就断了。建议在项目里立个规矩凡是用了toRefs或storeToRefs的地方返回变量名保持和源对象字段一致模板里不要二次重命名这样查问题能省一半时间。2.3 watch 和 watchEffect 的正确打开方式watch和watchEffect也是重灾区。表面看都是监听变化但使用的心智模型完全不同。watch是显式指定监听源只在源变化时触发强调精确控制。默认是懒执行也就是不立即执行回调除非配置immediate: true。监听源可以是 ref、reactive、getter 函数、数组。容易忽视的点直接传reactive对象时回调里拿到的 oldValue 会和 newValue 相同因为传入的是同一个对象引用修改发生在对象内部。想要拿到修改前的值就得用 getterwatch( () state.userInfo, (newVal, oldVal) { // 此时 oldVal 能拿到变化前引用 } )但注意如果state.userInfo是引用类型对象内部属性修改时 Vue 能捕获到变化可 oldVal 仍然是变化前的引用只是内容被改过了。真要深入对比还得用JSON.parse(JSON.stringify())做快照这适用于极少数对状态差异敏感的调试场景。watchEffect则是自动追踪副作用中使用到的响应式依赖谁变我跑谁。它默认立即执行一次用于建立依赖关系之后依赖的响应式变量一变就重新执行。它的特点是不关心具体哪个值变了只关心自己用到的东西变了没有。watchEffect(() { console.log(当前用户是, state.userInfo) })这里state.userInfo一变回调就会重新跑。我通常用watchEffect处理根据状态自动同步的副作用比如状态变化后自动写入 localStorage、自动调用接口同步缓存、自动记录埋点日志等。而watch更适合精确控制只在某个字段变化时需要拿新旧值做对比、处理异步流程去重、需要await或取消上一次请求的执行。补充一个几乎每篇文章都会漏的细节在script setup中watch和watchEffect都是全局导入的 API没有this概念所以也不用担心生命周期里怎么注销监听。组件卸载时 Vue 会自动停止这些副作用。真正需要手动 stop 的场景是在组合式函数里需要长期等事件或轮询的时候这时你可以拿到watchEffect的返回值手动调用stop()。3. 组件通信在 Vue 3 里的变化从过度设计到归于简洁3.1 v-model 的改动从一次绑定到多次绑定Vue 3 的v-model背后机制改了这才是组件通信里最容易被旧习惯拖累的点。Vue 2 的v-model相当于固定用value属性和input事件想要多个双向绑定就得自己命名xxx.sync巨麻烦。Vue 3 从机制上做了统一v-model可以绑定任意属性名并且默认不再强制叫 value / input。组件封装时写法变成!-- 子组件 Child.vue -- script setup langts defineProps{ visible: boolean keyword: string }() const emit defineEmits{ (e: update:visible, value: boolean): void (e: update:keyword, value: string): void }() /script !-- 父组件使用 -- Child v-model:visiblemodalVisible v-model:keywordsearchKeyword /这种多个 v-model 并行的设计比起.sync的散落写法更集中、读起来更顺。封装抽屉、弹层、筛选栏这类复合组件时这个能力是刚需。有一个坑必须提醒如果你沿用 Vue 2 的写法在子组件里声明props: [value]然后$emit(input)在 Vue 3 里是不生效的。Vue 3 里默认的 v-model 是modelValue属性和update:modelValue事件。迁移时最容易出现的就是弹窗组件的 visible 不生效这类问题原因基本都是 props 名字对不上。3.2 defineProps、defineEmits、defineExpose 的显式声明规则script setup里没有办法用export default声明 props所有对外接口都靠编译宏解决。这就带出一个特性defineProps、defineEmits、defineExpose都是编译期宏import 都不需要但它们必须在script setup的顶层调用不能放进函数或者 if 分支里。defineProps的类型写法很实用script setup langts interface Props { title: string count?: number tags?: string[] } const props definePropsProps() // 如果需要默认值用 withDefaults withDefaults(definePropsProps(), { count: 0, tags: () [] }) /script注意tags是数组时必须用函数返回默认值防止多个组件实例共享同一个默认数组引用。这个细节是很多内存泄漏和隐藏 bug 的源头。props本身是只读的子组件里不要试图直接修改 props 的属性这是 Vue 的双向数据流设计的基础逻辑。defineExpose解决的是父组件模板 ref 访问子组件内部方法的问题。在script setup里组件的绑定默认是关闭的外部拿不到组件实例内部的数据除非显式 defineExposescript setup langts function resetForm() { // ... } defineExpose({ resetForm }) /script !-- 父组件 -- Child refchildRef / script setup const childRef ref(null) childRef.value?.resetForm() /script这也是 Vue 3 和 Vue 2 一个显著的体验差异Vue 2 只要拿到实例内部方法全开放Vue 3 默认关闭可见性要什么给什么需要开发者主动声明。从封装角度看这是更安全的。但项目里如果封装第三方组件库的二次包裹层记得在包裹层里手动defineExpose透传底层方法否则业务方访问组件内部能力会各种碰壁。3.3 provide/inject跨层级共享状态但别把自己绕进去provide/inject在 Vue 3 里被重视了很多因为它配合 Composition API 用起来特别顺手。在组件树顶层向上供给任意深度的子组件都能注入。!-- 根组件 -- script setup langts import { provide, ref } from vue const appConfig ref({ theme: dark, locale: zh-CN }) provide(appConfig, appConfig) provide(updateConfig, (newConfig) { appConfig.value newConfig }) /script !-- 任意子组件 -- script setup langts import { inject } from vue const appConfig inject(appConfig) const updateConfig inject(updateConfig) function changeTheme() { updateConfig?.({ ...appConfig?.value, theme: light }) } /script这里有几个实操经验值得记下来。一是inject的 key 尽量用Symbol或统一导出的常量避免字符串 key 在大型项目里撞名。二是inject最好给默认值不然祖先组件一旦忘了 provide子孙组件直接拿 undefined 报错。三是如果inject的字段本身是响应式对象最好保持注入方不直接修改它只通过 provide 方传入的方法来改这样数据的修改路径是单向可追踪的否则跨层级乱改很难定位 bug。3.4 插槽在下透传属性在上——容易被忽略的边界行为组件通信里还有一个经常被忽略的角色属性透传attribute fallthrough。当你在子组件内没有显式声明某个 propVue 3 会把父组件传过来的额外属性自动挂到子组件根元素上这就是所谓的$attrs透传行为。实际操作中类名透传、事件透传、>script setup langts import { useAttrs } from vue const attrs useAttrs() /script template div CustomChild v-bindattrs / /div /template插槽方面script setup里useSlots能获得插槽对象需要判断某插槽是否存在时很实用。实际封装复杂布局组件时推荐始终用v-if包裹具名插槽避免无内容时渲染多余的空容器导致布局缝隙。4. 从 Vue 2 迁移到 Vue 3我在项目中踩过的高频坑4.1 filter 被移除全局 API 全面收敛Vue 3 干了一件翻旧账的事——内置过滤器filter被彻底移除了。官方理由很直接过滤器本质上是具名函数和普通方法在逻辑上高度重复保留它反而增加概念负担。迁移时所有自定义过滤器都要改写成普通函数或 computed 属性// 迁移前 Vue 2 p{{ price | formatPrice }}/p // 迁移后 Vue 3直接用函数 script setup const formatPrice (value) ¥${Number(value).toFixed(2)} /script template p{{ formatPrice(price) }}/p /template全局 API 的变化也很伤人。Vue.use()、Vue.mixin()、Vue.prototype等都是构造器模式Vue 3 应用实例化后与全局 API 分离初始化逻辑变成了createApp返回的 app 实例上的方法// Vue 2 Vue.use(MyPlugin) Vue.prototype.$bus new Vue() // Vue 3 const app createApp(App) app.use(MyPlugin) app.config.globalProperties.$bus new EventBus()Vue 2 项目里凡是挂在原型上的工具方法、事件总线迁到 Vue 3 都必须改写成app.config.globalProperties或在组合式函数内部维护。最痛苦的是插件生态很多老插件如果没升级到 Vue 3 兼容版本就得找替代品。4.2 生命周期函数名的变化以及 setup 里的生命周期用法Vue 3 把所有生命周期都改了前缀但迁移项目里最容易出问题的地方是beforeDestroy和destroyed改名成为beforeUnmount和unmounted。如果你还在组件里写beforeDestroyVue 3 不会给出任何警告只是这段逻辑永远不执行——排查这种 bug 简直噩梦。// Vue 2 beforeDestroy() { clearInterval(this.timer) } // Vue 3 Options API beforeUnmount() { clearInterval(this.timer) } // 或 script setup 里 import { onBeforeUnmount } from vue onBeforeUnmount(() { clearInterval(timer) })onMounted、onUnmounted、onActivated、onDeactivated在script setup里都是导入函数使用时机上几乎没有差别但有一个细微点onActivated只在配合KeepAlive时才有意义平时组件切换不会触发。写过 Vue 2 的人有记忆缓存列表状态的习惯但在 Vue 3 里建议在组件层面明确设计状态存储位置不要依赖 activated/deactivated 去做隐式的状态恢复。4.3 模板编译的细节变化key、v-if 和 v-for 共存Vue 3 对模板编译做了一堆优化但有几个行为变化非常容易忽略。第一v-if和v-for的优先级变了。Vue 2 中v-for的优先级比v-if高意味着v-if在每次循环里都会被评估Vue 3 中v-if优先级更高所以同一个元素上v-if和v-for共存时v-if无法访问v-for里的变量。官方建议是永远不要在同一个元素上写这两个指令。解耦的办法是先用 computed 过滤列表再渲染或者在外层套一层template用v-if控制展示。!-- 推荐computed 过滤后渲染 -- template v-iffilteredList.length li v-foritem in filteredList :keyitem.id{{ item.title }}/li /template script setup const filteredList computed(() { return list.value.filter(item item.isVisible) }) /script第二key不再自动绑定在template标签上。Vue 3 里v-for在template上循环时如果模板内部有多个根节点循环时必须在每个根元素上手动加key而不是只在template上加。这个坑在封装表格列、循环创建片段时很常见。第三fragment带来了多根组件的福音但响应式数据和样式继承会受影响。多根组件没法自动继承$attrs如果封装组件时需要父组件传进来的class挂到多个根得手动处理。4.4 Teleport、Suspense 和新组合 API 一起用项目体验能上一个台阶除了迁移旧代码Vue 3 最大的爽点在新特性。Teleport用来把组件渲染到指定 DOM 节点下最常见的场景是弹窗、通知、全局 loading。它解决的不只是样式层级问题而是脱离当前组件树的位置约束Teleport tobody div v-ifvisible classmodal-mask div classmodal-content slot / /div /div /Teleport弹层脱离组件 DOM 层级后z-index 冲突和 overflow 裁剪问题基本绝迹。值得注意的是Teleport还有disabled属性在移动端适配时很有用——某些容器内需要保留弹层位置而另一些场景要把弹层 degrade 到 body可以在运行时动态控制。Suspense则是和异步组件搭配使用的。它包裹异步依赖组件时可以展示 fallback 内容等异步组件加载完成再渲染正式内容。在真实业务里我的建议是别拿它做路由级别的懒加载等待层路由懒加载用组件本身的 loading 态就够了Suspense更适合组件内部存在异步依赖的场景比如页面里某个区块依赖远程配置后再渲染。4.5 我自己的迁移节奏和团队落地建议项目迁移这事我不建议大爆炸式重写。我在不少团队里看到过上来就把所有.vue文件全改一遍结果状态管理、组件通信逻辑屎山一样绕最后只能回滚。更稳的节奏是三步走第一步先升级依赖Vue 2.7 的兼容桥接版本里很多写法是同时支持 Options 和 Composition 的这时候重点检查全局 API 变化、filter 移除、事件总线替换这类影响面的问题。第二步逐步改造低频组件把纯展示组件从 Options 改写成script setup。这个阶段的主要目的是让团队适应新的代码组织方式。第三步针对状态复杂的高频业务组件逐个用组合式函数重构这个过程中顺便把组件拆得更细、把响应式状态收敛到 useXxx 函数里。每个阶段都要做一次全量回归。迁移这事本质不是技术问题而是管理和节奏问题。步子迈得小坑踩得少回头来维护也从容。最后分享一个我在实际项目里验证过的习惯vue3 项目里如果一个组件开始超过 300 行优先思考能不能拆组合式函数而不是继续在script setup里堆ref和watch。这样既保住了响应式的体验也让代码的可读性收敛到可控范围。Vue 3 的组合式思想不是让你把所有东西都塞进 setup而是把变化点聚合成一个个可独立测试、独立维护的小单元——这才是我认为的 vue3 知识汇总里最重要的一课。