Vue3 发布已久，Composition API、响应式重构、TypeScript 支持等特性让人眼前一亮，但真正深入项目后，才发现“会用”和“用对”之间隔着不少难点。本文梳理了 Vue3 开发中高频踩坑的重点难点，希望能帮你少走弯路。
一、响应式系统的“糖”与“坑”
Vue3 用 Proxy 代替了 Object.defineProperty，解决了 Vue2 中对象新增属性不响应、数组索引和长度监听等历史难题。但新的响应式 API 也带来了新的心智负担。
1. ref 与 reactive 的本质区别
很多新手纠结“到底用 ref 还是 reactive”。简单原则是：
- ref：适合基本类型，以及可能被整体替换的对象。
- reactive：适合复杂嵌套对象，如表单数据、配置项。
真正的难点在于理解它们的响应性传递机制。
javascript
// reactive 的局限性：解构会丢失响应性
const state = reactive({ count: 0, name: 'Vue' })
let { count } = state
count++ // 不会触发更新！
// 解决：toRefs
const { count: countRef } = toRefs(state)
countRef.value++ // 保持响应
reactive 返回的是一个原始对象的 Proxy，当你解构或展开时，拿到的只是普通值，响应性会断裂。凡是需要解构的场景，都请用 toRefs 包裹。
2. ref 自动解包的那些“例外”
模板中 ref 自动解包，不需要 .value，这很舒服。但在以下场景中，解包行为需要特别留意：
javascript
// reactive 数组中的 ref 会自动解包
const reactiveArr = reactive([ref(1), ref(2)])
console.log(reactiveArr[0]) // 1 （自动解包）
// 但是普通数组中的 ref 不会自动解包
const normalArr = [ref(1), ref(2)]
console.log(normalArr[0].value) // 1，必须手动 .value
记忆技巧：只有作为 reactive 对象的属性时，ref 才会在模板和该 reactive 上下文里自动解包。独立存在的 ref 或存于普通数组/对象中时，需要手动 .value。
3. 解决“整体替换”导致 reactive 响应性丢失
这是最常见的坑：你给一个 reactive 变量整体赋了新对象，页面不更新。
javascript
let data = reactive({ items: [] })
// 错误做法
data = { items: [1,2,3] } // 丢失响应性！
// 正确做法1：使用 ref 包裹
const data = ref({ items: [] })
data.value = { items: [1,2,3] } // 保持响应
// 正确做法2：保持 reactive 引用，修改属性
Object.assign(data, { items: [1,2,3] })
结论：如果你的数据可能被整体替换，直接用 ref 会比 reactive 更安全直观。
二、Composition API 里的细节魔鬼
Composition API 让逻辑复用达到新高度，但“自由”背后有很多隐藏规则。
1. watch vs watchEffect，选谁？
watchEffect 会自动追踪内部依赖并立即执行，watch 则需要显式指定数据源，默认惰性。
难点在于不当使用导致无限循环或遗漏依赖：
javascript
// 危险：在 watchEffect 中修改依赖值，可能死循环
const count = ref(0)
watchEffect(() => {
count.value++ // 每次执行都触发自己！
})
// 正确：更精准地用 watch
watch(count, (newVal) => {
// 可控的后续操作
})
使用场景判断：
watchEffect：你不在乎具体依赖哪些值，只希望它们变化时执行某操作（如日志、调试）。
watch：需要新老值对比，或者需要懒执行、精确控制触发时机。
2. 组合式函数的响应性“契约”
自己封装 useXxx 时，必须遵循“返回 ref 而非值”的原则，否则调用方会丢失响应。
javascript
export function useMouse() {
const x = ref(0)
const y = ref(0)
// ... 更新逻辑
// 错误：return { x: x.value, y: y.value } // 丢响应
return { x, y } // 保持 ref
}
如果调用方希望解构不丢失响应，记得返回时用 reactive 包装或用 toRefs 转换。
3. 生命周期的“失效”危险
setup 中的生命周期钩子只能在 setup 内同步调用。如果你在异步回调里注册生命周期，它不会生效。
javascript
setup() {
setTimeout(() => {
onMounted(() => { /* 无效 */ })
}, 0)
}
这经常发生在条件性注册生命周期的场景，请务必保持在同步执行流中。
三、新组件特性：强大但易用错
1. Teleport：传送的是 DOM，不是上下文
Teleport 可以把子节点渲染到任意 DOM 节点，但组件上下文仍然属于父组件。这意味着 props、事件、provide/inject 都正常工作。常见误解是以为传送后组件隔离开了，其实不是。
难点在于样式作用域：scoped 样式不会穿透到传送后的内容，需要全局样式或 :deep() 来解决。
2. Suspense 与异步组件
Suspense 可以优雅地处理异步组件加载状态，但它依赖于实验性功能，且对于嵌套路由、异步数据请求还需要与 defineAsyncComponent 配合，在服务端渲染(SSR)中也有额外限制。目前要慎用于核心流程，小范围体验即可。
四、TypeScript 下的组件类型实践
Vue3 对 TS 的支持大幅提升，但写好类型安全的组件仍然有挑战。
1. Props 的类型推导
typescript
// 运行时声明
const props = defineProps({
name: { type: String, required: true }
})
// 类型声明（更推荐）
const props = defineProps<{
name: string
count?: number
}>()
// 设定默认值需要用 withDefaults
const props = withDefaults(defineProps<{
items: string[]
}>(), {
items: () => []
})
难点：当使用类型声明时，要提供默认值必须用 withDefaults，且默认值函数要返回符合类型的值。
2. 模板 ref 的类型
typescript
const divRef = ref<HTMLDivElement | null>(null)
获取组件实例时，需要使用 InstanceType 来推导暴露的类型，或者为组件定义 defineExpose。
五、不容忽视的编译优化与最佳实践
Vue3 在编译阶段做了静态提升、补丁标志、事件缓存等优化，性能更好，但这不代表你可以无限堆砌响应式对象。合理的组件分割、减少不必要的顶层响应式变量，依然很重要。
一些容易被忽略的点：
v-for 中的 ref 数组无法保证顺序，需要时请使用函数绑定。
v-if 和 v-for 优先级仍然相反，Vue3 中 v-if 优先级更高，不要混用在同一元素。
动态组件 <component :is> 配合 KeepAlive 时，对组件名称有严格要求。
写在最后
Vue3 的难点不在于 API 记忆，而在于理解其响应式运转机制与组合式的“数据契约”。这些经验大多是从一次次 bug 中总结出来的。如果你也有难倒过你的 Vue3 问题，欢迎在评论区聊聊，一起避坑。
黄俊煌是深圳市佰通科技有限公司的员工。
叶伟栋是深圳市佰通科技有限公司的员工。
Top comments (0)