Vue3 正式发布以来，组合式 API、响应式系统重构和 TypeScript 友好支持让前端项目的组织方式发生了显著变化。但很多从 Vue2 迁移过来的项目，或者刚接触 Vue3 的团队，在实际编码中仍然会遇到大量隐蔽的坑点。例如响应式数据被意外破坏、组件不触发更新、生命周期钩子导致空指针、构建配置遗漏造成运行时报错等。本文把这些问题拆解成几个关键方向，逐条说明注意事项并给出修正方案。
这些内容不仅适用于新项目，也适合正在做 Vue2 到 Vue3 升级的开发者参考。接下来的每一个小节都配有可运行的示例代码，读者可以直接复制到本地验证。
一、响应式基础：ref与reactive的边界与常见错误
组合式API中最容易出错的地方就是ref和reactive的混用。reactive通过Proxy代理对象，只有对代理对象的属性进行读写才会触发依赖收集和更新，一旦把reactive声明的变量整体重新赋值，原来的代理引用就丢失了，后续对旧变量的操作不会触发视图更新。这是一个非常典型的错误。相较之下，ref把值包装在value属性中，对.value赋值可以替换整个对象并保持响应性。
下面这段代码展示了错误和正确的用法。错误用法中，reactive变量被整体替换后，组件无法感知数据变化；正确用法则通过修改属性或改用ref来避免问题。开发者在封装组合式函数时，尤其要注意返回值的结构，如果直接返回reactive对象的属性，也要避免在函数外部重新赋值的操作。
import { reactive, ref, toRefs } from 'vue'
// 错误：整体替换 reactive 对象
export function useCounterError() {
let state = reactive({ count: 0 })
function resetWrong() {
// 试图整体替换，响应性丢失
// state = { count: 0 } // 如果取消注释，运行时不会触发更新
}
return { state, resetWrong }
}
// 正确：修改属性或使用 ref
export function useCounterOk() {
const state = ref({ count: 0 })
function reset() {
state.value = { count: 0 }
}
return { state, reset }
}
// 解构响应式对象时使用 toRefs
const obj = reactive({ name: 'Vue', version: 3 })
const { name, version } = toRefs(obj)
// name 和 version 保持响应式
除了整体替换问题，解构也会破坏响应性。直接对reactive对象进行解构，得到的普通值不再具有响应能力。此时应当使用toRefs把每个属性转换为ref，或者使用toRef针对单个属性。另外，shallowRef和shallowReactive只对第一层做响应式处理，如果确定数据是大型只读列表，可以用它们避免深层代理带来的性能开销，但必须清楚其副作用。
二、组合式API与模板语法的迁移注意点
<script setup> 是Vue3推荐的单文件组件写法，编译后会自动暴露顶层绑定并生成正确的props和emits声明。但它也有一些限制，例如组件无法通过name选项显式命名（虽然可以通过文件名推断），并且所有在script标签内声明的变量都会暴露给模板，可能造成命名冲突。需要额外注意defineProps和defineEmits只能在编译宏范围内使用，不能在普通函数内部调用。
v-model在Vue3中的底层实现已经从value/input改成modelValue和update:modelValue，这使得一个组件可以同时绑定多个v-model。例如子组件需要分别为title和content建模时，父组件可以写v-model:title和v-model:content。同时，.sync修饰符被移除，自定义修饰符需要通过props声明中的modelModifiers对象来访问。这些变化如果沿用Vue2习惯，会出现属性未定义或事件不触发的问题。
<template>
<ChildComponent v-model:title="pageTitle" v-model:content="pageContent" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'
const pageTitle = ref('默认标题')
const pageContent = ref('正文内容')
</script>
子组件内部需要声明对应的modelValue和事件，示例代码如下。值得注意的是，如果使用了自定义修饰符，还需要在props中声明titleModifiers和contentModifiers对象。这些细节在官方文档中分散在多个章节，实际开发时经常会遗漏。
// 子组件 ChildComponent.vue 的 script setup 部分
<script setup lang="ts">
defineProps({
title: String,
content: String,
titleModifiers: { default: () => ({}) },
contentModifiers: { default: () => ({}) }
})
defineEmits(['update:title', 'update:content'])
</script>
<template>
<input :value="title" @input="$emit('update:title', $event.target.value)" />
<textarea :value="content" @input="$emit('update:content', $event.target.value)" />
</template>
事件监听方面，$listeners被合并到$attrs中，.native修饰符也被移除。父组件传递给子组件的所有非props属性都会进入$attrs，子组件可以通过v-bind="$attrs"透传。作用域插槽的语法统一为v-slot，slot和slot-scope不再支持。这些迁移点虽然不大，但在混合项目中非常容易出现编译警告或运行时错误。
三、TypeScript集成与构建配置中的陷阱
Vue3对TypeScript的支持大幅提升，但类型推断仍然存在一些容易忽略的细节。defineProps的运行时声明和类型声明是两种不同的机制：如果只用类型参数声明props，编译后类型信息会丢失，运行时无法验证。如果需要在运行时校验，就必须使用对象语法声明每个prop的type、required和default。与此同时，在<script setup lang="ts">中，ref声明的变量在模板中自动解包，但在TS代码中访问时需要通过.value，而这种差异有时会导致类型缩小失效。
// 类型声明式 props：编译期检查，运行时无校验
<script setup lang="ts">
interface Props {
title: string
count?: number
}
const props = defineProps<Props>()
</script>
// 运行时声明式 props：运行时校验
<script setup lang="ts">
const props = defineProps({
title: { type: String, required: true },
count: { type: Number, default: 0 }
})
</script>
编辑器插件的选择也会影响开发体验。Vue2时期常用的Vetur已不再维护，建议切换到Volar。项目tsconfig中需要包含vue-tsc的类型检查步骤，并为.vue文件声明全局类型。对于全局组件和自定义插件的类型提示，需要通过modules声明合并扩展GlobalComponents接口。缺少这些配置时，编辑器不会报错，但运行构建时的类型检查会失败，造成CI流程中断。
构建层面，Vue3项目大多基于Vite或升级后的Vue CLI。迁移时要注意vue-loader版本、babel插件以及CSS预处理的依赖是否兼容。特别是当项目使用webpack时，需要手动配置vue-loader的编译选项；而Vite则原生支持Vue SFC，但插件版本要与Vue版本匹配。环境变量在Vite中使用import.meta.env访问，与Vue2的process.env完全不同，混用会导致变量读取不到。
四、性能优化与调试的实用技巧
Vue3的响应式系统默认是惰性的，只有被访问的数据才会追踪依赖，这为性能优化提供了更大空间。对于大列表渲染，可以结合v-memo指令缓存子树，或者通过异步组件配合Suspense实现代码分割和加载状态管理。还有一个常见误区是过度使用watch和computed：watch的深度监听会递归遍历对象，在数据规模大时显著增加开销。如果只需要监听某个属性，应当优先使用watch的getter函数形式。
import { watch, shallowRef } from 'vue'
// 错误：深层监听大对象
watch(largeObject, (newVal) => {
// 深度遍历开销大，且 newVal 可能不是预期结构
})
// 正确：监听特定属性
watch(() => largeObject.count, (newVal) => {
// 只追踪 count 属性
})
// 大列表使用 shallowRef 只对整体引用做响应
const bigList = shallowRef([...Array(10000).keys()])
调试方面，Vue Devtools浏览器扩展提供了组件树、状态检查和事件时间线等能力。当遇到组件不更新的问题时，可以先在Devtools中查看响应式数据是否被正确追踪。如果数据确实变化但视图没有更新，需要检查是否违反了响应性规则，例如直接通过索引修改数组或给对象添加新属性。Vue3虽然通过Proxy解决了Vue2中数组索引和对象新增属性的问题，但对于ref解构、reactive整体替换等操作仍然需要开发者保持警惕。
最后，升级到Vue3不必一次性重写所有代码，可以利用兼容构建版本逐步迁移。官方提供的迁移指南和自动化工具能够识别大多数已移除的API。迁移完成后，建议开启构建日志中的警告信息，并结合eslint-plugin-vue的Vue3规则集统一团队编码风格，减少后续维护中的意外错误。