前言
Vue 3 作为 Vue.js 的重大版本更新，带来了 Composition API、更好的 TypeScript 支持、性能优化等诸多改进。然而，在从 Vue 2 迁移或直接上手 Vue 3 的过程中，开发者们常常会遇到一些"坑"。本文旨在汇总这些常见问题，并提供详细的解决方案和最佳实践，帮助你更顺畅地使用 Vue 3。
1. 响应式系统 (Reactivity) 的"坑"
Vue 3 使用 Proxy 重构了响应式系统，虽然更强大，但也带来了新的理解和使用门槛。
1.1 解构响应式对象导致失去响应性
这是最常见的错误之一。直接解构 reactive 或 ref 的 .value 会破坏响应式连接。
javascript
复制代码
// ❌ 错误示例
import { reactive } from 'vue';
const state = reactive({ count: 0 });
const { count } = state; // 解构后，count 不再是响应式的
count++; // 视图不会更新
// ✅ 正确做法 1：使用 toRefs
import { reactive, toRefs } from 'vue';
const state = reactive({ count: 0, name: 'Vue' });
const { count, name } = toRefs(state); // 现在 count 和 name 都是响应式 ref
count.value++; // 视图会更新
// ✅ 正确做法 2：直接访问原对象属性
state.count++; // 视图会更新
1.2 直接替换 reactive 对象的引用
reactive 绑定的是对象的引用，直接赋值一个新对象会丢失响应性。
javascript
复制代码
// ❌ 错误示例
let state = reactive({ data: null });
state = { data: fetchData() }; // 错误！state 的响应式连接断了
// ✅ 正确做法：修改对象的属性
state.data = fetchData(); // 正确，保持了响应性
// 或者使用 ref
import { ref } from 'vue';
const state = ref({ data: null });
state.value = { data: fetchData() }; // 正确，ref 的 .value 可以被整体替换
1.3 在异步操作中访问未定义的响应式属性
如果在 setup 或 onMounted 等钩子中异步获取数据并赋值给响应式对象，需要确保属性已初始化。
javascript
复制代码
// ❌ 可能导致问题
const state = reactive({});
setTimeout(() => {
state.user = { name: 'Alice' }; // 如果模板在赋值前访问 state.user.name 会报错
}, 1000);
// ✅ 更安全的做法：预先定义属性结构
const state = reactive({
user: null, // 或 user: {}
list: []
});
// 或者使用可选链操作符 ?. 和空值合并 ?? 来防御
2. Composition API 使用陷阱
2.1 在生命周期钩子外使用 onMounted/onUpdated 等
生命周期钩子（如 onMounted, onUpdated）必须在 setup() 函数或
3.2 使用 defineExpose 暴露组件内部方法或属性
默认情况下，
4. 路由 (Vue Router 4) 的常见问题
4.1 路由守卫中使用 Composition API
在 Vue Router 4 的路由守卫中，不能直接使用 setup 中的响应式变量或生命周期钩子。
javascript
复制代码
// router/index.js 或路由守卫文件中
import { createRouter, createWebHistory } from 'vue-router';
import { useUserStore } from '@/stores/user'; // 假设使用 Pinia
const router = createRouter({
history: createWebHistory(),
routes: [...]
});
// 全局前置守卫
router.beforeEach((to, from) => {
// ❌ 错误：不能在这里调用 composable
// const userStore = useUserStore();
// ✅ 正确：通过其他方式获取状态，例如从 localStorage 或直接导入 store 实例
const userStore = useUserStore(); // 注意：这要求 store 已在应用层初始化
if (to.meta.requiresAuth && !userStore.isLoggedIn) {
return '/login';
}
});
4.2 路由组件内获取路由参数和查询
使用 useRoute 和 useRouter 组合式函数。
html
复制代码
5. 状态管理 (Pinia) 的最佳实践与坑点
Pinia 是 Vue 3 官方推荐的状态管理库，替代 Vuex。
5.1 在 setup 外使用 store
在组件 setup 之外（例如路由守卫、工具函数中）使用 store，需要确保 Pinia 实例已安装到应用中。
javascript
复制代码
// stores/user.js
import { defineStore } from 'pinia';
export const useUserStore = defineStore('user', {
state: () => ({ name: '' }),
actions: {
setName(name) { this.name = name; }
}
});
// 在非组件文件中使用（例如 axios 拦截器）
import { useUserStore } from '@/stores/user';
// ❌ 直接调用会报错，因为此时没有活跃的 Pinia 实例
// const store = useUserStore();
// ✅ 正确：在应用初始化后，通过导入的 store 文件直接调用
// 方法1：在能访问到 app 的地方传入 pinia 实例（不常见）
// 方法2：在 store 动作内部处理非响应式逻辑，或确保调用时组件已挂载
更安全的模式：在组件或组合式函数内调用 store 动作，将必要的业务逻辑封装在 store 的 actions 中。
5.2 Store 的响应式解构
与 reactive 类似，直接解构 store 的状态也会失去响应性。使用 storeToRefs。
html
复制代码
6. 性能优化相关陷阱
6.1 不必要的组件重新渲染
Vue 3 的响应式系统很高效，但传递不必要的响应式对象或函数仍会导致子组件不必要的更新。
html
复制代码
6.2 大型列表使用 v-for 未加 key
这虽然是 Vue 2 就有的问题，但在 Vue 3 中依然重要。同时，避免在 v-for 中使用复杂表达式。
html
复制代码
{{ item.name }}
{{ item.name }}
7. TypeScript 集成注意事项
7.1 为组件 Props 和 Emits 定义类型
使用 TypeScript 时，明确定义 props 和 emits 的类型可以获得更好的类型推断和 IDE 支持。
html
复制代码
7.2 模板 Ref 的类型定义
为模板 ref 指定类型，以访问组件实例或 DOM 元素的属性。
html
复制代码
8. 构建与部署相关
8.1 公共路径 (publicPath) 配置
如果应用部署在子路径下（如 https://example.com/my-app/），需要在构建配置中设置正确的 publicPath。
javascript
复制代码
// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defin