---
### **1. 响应式 API 误用**
**问题**: 使用 `reactive` 包裹原始值（如 `number`/`string`）无效。
**解决**: 对原始值使用 `ref`，对象/数组使用 `reactive`。
---
### **2. 生命周期钩子名称变化**
**问题**: `beforeDestroy` 和 `destroyed` 未触发。
**解决**: 改用 `beforeUnmount` 和 `unmounted`。
---
### **3. 过滤器（Filter）废弃**
**问题**: 使用 `{{ value | filter }}` 报错。
**解决**: 改用计算属性或方法（如 `{{ filter(value) }}`）。
---
### **4. 全局 API 变更**
**问题**: `Vue.nextTick` 或 `Vue.set` 不可用。
**解决**: 通过 ESM 导入 `import { nextTick } from 'vue'`。
---
### **5. `v-model` 语法变更**
**问题**: 自定义组件中 `v-model` 行为与 Vue 2 不同。
**解决**: 使用 `modelValue` 和 `update:modelValue` 事件，或通过 `v-model:arg` 指定参数。
---
### **6. 事件发射需显式声明**
**问题**: 未声明的事件触发时警告。
**解决**: 使用 `defineEmits` 声明事件：
```js
const emit = defineEmits(['update:value']);
emit('update:value', newValue);
```
---
### **7. 模板引用（`ref`）名称冲突**
**问题**: 在 Composition API 中，`ref` 变量名与模板引用名冲突。
**解决**: 修改变量名或在模板中使用别名：`<div ref="elRef"></div>`。
---
### **8. TypeScript 类型推断问题**
**问题**: 组件选项类型不明确。
**解决**: 使用 `defineComponent` 包裹组件：
```ts
export default defineComponent({ /* ... */ });
```
---
### **9. 异步组件加载方式变更**
**问题**: `() => import('...')` 直接使用报错。
**解决**: 使用 `defineAsyncComponent`：
```js
import { defineAsyncComponent } from 'vue';
const AsyncComp = defineAsyncComponent(() => import('...'));
```
---
### **10. Fragment 根节点支持**
**问题**: 多根节点组件导致样式或逻辑异常。
**解决**: 确认父组件是否支持多根节点，或在外层包裹 `<div>`。
---
### **11. Teleport 目标容器未渲染**
**问题**: `<Teleport>` 内容未显示。
**解决**: 确保目标容器在 DOM 中存在（如 `<div id="modal"></div>`）。
---
### **12. 组合式函数（Composable）命名规范**
**问题**: 组合式函数命名混乱导致可读性差。
**解决**: 统一以 `use` 开头（如 `useFetch`）。
---
### **13. Props 直接修改警告**
**问题**: 直接修改 `props` 的值触发警告。
**解决**: 通过 `emit` 更新或使用 `v-model` 双向绑定。
---
### **14. 第三方库兼容性问题**
**问题**: Vue 2 插件（如 `Vuex 3`）无法在 Vue 3 使用。
**解决**: 寻找 Vue 3 兼容版本（如 `Vuex 4` 或 `Pinia`）。
---
### **15. 响应式数组操作失效**
**问题**: 直接通过索引修改数组元素无响应性。
**解决**: 使用 `push`/`splice` 或重新赋值：
```js
arr.value = [...arr.value, newItem];
```
---
### **16. CSS 作用域样式穿透失效**
**问题**: `::v-deep` 语法变更导致样式不生效。
**解决**: 改用 `:deep(.class)` 或 `::v-deep(.class)`。
---
### **17. `this` 在 Setup 中不可用**
**问题**: `setup()` 中访问 `this` 返回 `undefined`。
**解决**: 使用 Composition API（如 `ref`/`reactive`）替代 `this`。
---
### **18. 动态组件警告**
**问题**: 动态组件 `<component :is>` 导致控制台警告。
**解决**: 使用 `markRaw` 标记非响应式组件：
```js
import { markRaw } from 'vue';
components: { [key: string]: markRaw(Component) }
```
---
### **19. 自定义指令 API 变更**
**问题**: 指令生命周期钩子名称变更（如 `bind` → `mounted`）。
**解决**: 参考新 API 命名（`mounted`/`updated`/`unmounted`）。
---
### **20. `provide/inject` 需显式导入**
**问题**: `provide` 或 `inject` 未定义。
**解决**: 从 Vue 导入：
```js
import { provide, inject } from 'vue';
```
---
### **21. 代码分割与 Tree-shaking 失效**
**问题**: 构建产物包含未使用的代码。
**解决**: 确保使用 ESM 模块（如 `import { ref } from 'vue'` 而非 `import Vue from 'vue'`）。
---
### **22. Vue Router 4 路由守卫变更**
**问题**: `next()` 参数行为变化。
**解决**: 返回 `false` 取消导航，或返回路径字符串重定向。
---
### **23. 过渡类名变更**
**问题**: CSS 过渡类名（如 `v-enter` → `v-enter-from`）失效。
**解决**: 更新为 `v-enter-from`/`v-enter-active` 等新类名。
---
### **24. 错误处理机制变更**
**问题**: 全局错误处理器未生效。
**解决**: 使用 `app.config.errorHandler` 注册错误处理函数。
---
### **25. DevTools 兼容性问题**
**问题**: Vue 3 项目在 DevTools 中不显示。
**解决**: 升级到最新版 Vue DevTools 6.x+。
---
### **26. SSR 相关 API 变更**
**问题**: `serverPrefetch` 废弃。
**解决**: 在 `setup()` 中使用 `onServerPrefetch`。
---
### **27. 动态路由匹配问题**
**问题**: Vue Router 4 动态路由参数未更新。
**解决**: 监听路由参数变化：
```js
watch(() => route.params.id, (newId) => { /* ... */ });
```
---
### **28. 插槽语法变更**
**问题**: `slot-scope` 废弃。
**解决**: 使用 `v-slot` 或简写 `#`（如 `<template #header>`）。
---
### **29. 响应式对象解构丢失响应性**
**问题**: 解构 `reactive` 对象后属性失去响应性。
**解决**: 使用 `toRefs`：
```js
const state = reactive({ a: 1 });
const { a } = toRefs(state); // 保持响应性
```
---
### **30. Vuex 迁移至 Pinia**
**问题**: Vuex 4 在 Vue 3 中可用但推荐 Pinia。
**解决**: 逐步迁移到 Pinia（更简洁的 API 和 TypeScript 支持）。
---
### **附加问题**
31. **`watch` 监听响应式对象属性**
**解决**: 使用 `() => state.value.key` 作为监听源：
```js
watch(() => state.value.key, (newVal) => { /* ... */ });
```
32. **`<script setup>` 语法糖的限制**
**解决**: 复杂逻辑拆分为组合式函数，或使用普通 `<script>` 配合 `setup()`。
33. **Vue 3 废弃 `$children`**
**解决**: 使用 `ref` 获取子组件实例：
```vue
<Child ref="childRef" />
<script setup>
const childRef = ref(null);
</script>
```
---
### 总结
Vue 3 的核心变化包括 Composition API、响应式系统重构、以及生态工具更新。通过遵循官方迁移指南、使用 TypeScript 增强类型推断，并关注工具链（Vite、Pinia、Vue Router 4）的更新，可显著降低开发风险。
