Vue3 实战爬坑日记｜半年项目踩坑总结
从 Vue2 无缝切换到 Vue3 + Setup 语法糖，本以为只是写法升级，上手做企业级项目才发现，Vue3 的响应式原理、语法规范、生命周期全变了。
这半年踩过无数玄学BUG，从视图不更新到组件通信失效，从样式穿透无效到打包报错，每一个坑都是实打实的实战经验。这篇日记不搞理论，只分享能帮你少加班的干货。
一、响应式核心：最容易踩的天坑
- reactive 直接赋值，视图彻底不更新
这是我第一个卡了10分钟的坑，也是 Vue3 新手必踩。
<script setup>
import { reactive } from 'vue'
const list = reactive([])
// 错误写法：直接赋值丢失响应式引用
list = [1,2,3]
</script>原因：reactive 是代理对象，直接赋值会覆盖引用，断开响应式连接。
解决方案：基础数据/数组用 ref，对象用 reactive 做修改，不直接赋值。
- props 直接解构，响应式直接丢失
<script setup>
// 错误写法
const { title } = defineProps(['title'])
</script>血泪教训：Setup 语法糖中直接解构 props 会破坏单向数据流，失去响应式。
解决方案：使用 toRefs 保持响应式。
<script setup>
import { toRefs } from 'vue'
const props = defineProps(['title'])
const { title } = toRefs(props)
</script>- watch 监听 reactive 对象，监听不到变化
默认浅监听，嵌套属性修改完全不触发，必须开启深度监听。
最佳实践：监听对象属性用 getter 函数，比 deep 更轻量。
二、组件通信：告别 Vue2 老旧写法
- 自定义事件：defineEmits 不要手动导入
Vue3 语法糖自带编译器宏，不需要从 vue 导入，导入反而报错。
<script setup>
// 正确写法
const emit = defineEmits(['change'])
</script>- 父子组件双向绑定：v-model 升级踩坑
Vue3 移除了 .sync 修饰符，统一用 v-model，配合 defineModel 极简写法，很多人还在沿用 Vue2 的写法导致绑定失效。
- 跨级通信：provide/inject 响应式失效
传递普通值无响应式，必须传递 ref/reactive 对象，这是项目中最容易忽略的细节。
三、生命周期与异步：90% 的BUG都出在这里
- onMounted 获取不到DOM元素
异步请求、v-if 控制的DOM，在 onMounted 中直接获取会返回 null。
解决方案：搭配 nextTick 等待DOM渲染完成。
- 异步更新队列：数据改了，DOM没刷新
Vue3 响应式更新是异步的，修改数据后立即操作DOM，永远拿不到最新结果，nextTick 是解决这类问题的万能钥匙。
四、样式与DOM：Vue3 专属坑点
- scoped 样式穿透失效
Vue2 使用 /deep/，Vue3 中废弃，统一使用 :deep()，这是样式不生效的头号原因。
- Teleport 传送门：DOM位置正确但样式错乱
弹窗、抽屉常用 Teleport，因为脱离了组件作用域，scoped 样式无法生效，需要单独处理样式。
五、工程化与语法糖：编译级别的坑
- 顶层 await 直接用，打包后报错
Setup 语法糖支持顶层 await，但必须配合 Suspense 组件使用，否则生产环境直接崩溃。
- 动态组件 is 属性用法变更
Vue3 动态组件必须用 component 标签，且写法有调整，沿用 Vue2 写法会渲染失败。
六、Pinia 状态管理：替代Vuex后的新坑
- 解构 store 数据会丢失响应式，必须用 storeToRefs
- 异步 action 中修改状态，无需像 Vuex 一样用 commit，直接修改即可
七、写在最后
用了半年 Vue3，我最大的感悟是：所有玄学BUG，本质都是对响应式原理和语法糖的不理解。
Vue3 比 Vue2 更严谨、更灵活，但也对开发者的基础要求更高。不要再用 Vue2 的思维写 Vue3，吃透响应式、编译器宏、生命周期这三大核心，你会发现 Vue3 真的很香。
这些坑都是我在真实项目中一个个踩出来的，如果你也遇到了莫名其妙的BUG，不妨对照这篇日记检查一下，大概率能找到答案。
前端路漫漫，一起避坑，一起成长。
评论