Vue 2 Options API 怎么迁移到 Vue 3 组合式 API？有哪些最佳实践步骤？

在开始迁移之前，先确认当前项目是否依赖 Vue 2 特有的插件或库（如 vue-router 3.x、Vuex 3.x 等）。如果依赖，需要同步升级到 Vue 3 兼容版本（如 vue-router 4.x、Pinia 替代 Vuex）。另外，检查项目中是否存在大量使用 this 访问响应式数据的逻辑，这是组合式 API 中需要改写的主要部分。建议从页面组件或小型功能模块开始试点，避免一次性直接重构整个项目。

在开始迁移之前，先确认当前项目是否依赖 Vue 2 特有的插件或库（如 vue-router 3.x、Vuex 3.x 等）。如果依赖，需要同步升级到 Vue 3 兼容版本（如 vue-router 4.x、Pinia 替代 Vuex）。另外，检查项目中是否存在大量使用 `this` 访问响应式数据的逻辑，这是组合式 API 中需要改写的主要部分。建议从页面组件或小型功能模块开始试点，避免一次性直接重构整个项目。

推荐采用“组件级”替换策略，即每次只将一个组件的 Options API 改写为 Composition API。对于复杂组件，可以先用 `mixins` 抽取公共逻辑作为过渡，待熟悉组合式 API 后再将 mixin 替换为 `useXxx` 函数。操作时，先使用 `setup()` 函数替换 `data`、`computed`、`methods` 和 `watch`，保持原有逻辑不变。注意将 `this` 引用改为通过 `ref` 或 `reactive` 声明的变量，并去除 `this` 前缀。

这个前提检查很容易被忽略。例如，如果你还在用 vue-router@3，直接升级组件后路由不会工作，必须先升级路由库。同样，Vuex 3.x 在 Vue 3 中不兼容，官方推荐改用 Pinia 或 Vuex 4.x。可以先运行 vue upgrade（如果使用 Vue CLI）或参考官方迁移构建版本 @vue/compat 来逐步过渡，但要注意兼容模式会增加打包体积，后续仍需彻底移除。

逐步替换策略：组件级改写

推荐采用“组件级”替换策略，即每次只将一个组件的 Options API 改写为 Composition API。对于复杂组件，可以先用 mixins 抽取公共逻辑作为过渡，待熟悉组合式 API 后再将 mixin 替换为 useXxx 函数。操作时，先使用 setup() 函数替换 data、computed、methods 和 watch，保持原有逻辑不变。注意将 this 引用改为通过 ref 或 reactive 声明的变量，并去除 this 前缀。

改写时，如果组件代码较长，可以先把 data 和 computed 搬进 setup，再处理 methods。每次只改动一个文件，运行单元测试或手动验证后再继续。这样如果出现问题，回退范围也小。另外，mixins 作为过渡方案时，需注意 Vue 3 中 mixins 仍然可用，但会与组合式 API 混用增加复杂度，建议尽快替换为组合函数。

响应式数据改写：ref 与 reactive 的选择

将 data() 返回的对象改为使用 ref() 或 reactive() 声明。对于简单类型（如字符串、数字），用 ref；对于对象或数组，用 reactive 或 ref 包裹。注意：在模板中，ref 声明的值会自动解包，但在 JavaScript 中需通过 .value 访问。一个常见坑是忘记在 watch 或 computed 内部对 ref 变量使用 .value，导致逻辑无法正确触发更新。建议在 setup 函数顶部统一声明所有响应式变量，并显式标注类型（如果使用 TypeScript）。

在实际操作中，如果你使用 reactive 包裹一个对象，后续直接替换整个对象（如 state = newState）会丢失响应性，必须通过属性赋值或使用 Object.assign。另外，如果对象层级较深，可以考虑使用 ref 包裹整个对象，并在模板中自动解包，但 JavaScript 中仍需要 .value。建议先用一个简单组件尝试两种方式，观察响应式行为，再确定团队的风格。

生命周期调整：钩子映射与常见误区

Options API 中的 created、mounted、beforeDestory 等生命周期钩子需要对应替换为组合式 API 的 onMounted、onBeforeUnmount 等函数。注意：beforeCreate 和 created 中的逻辑通常可以直接移到 setup 函数中，因为 setup 的执行时机相当于这两个钩子的合并。destroyed 钩子对应 onUnmounted，而 beforeDestroy 对应 onBeforeUnmount。另外，watch 选项中 immediate 属性可通过在 watch 函数中手动触发一次回调来实现。

有一个容易忽略的点：如果 created 中使用了 this.$el 或操作 DOM，在 setup 中无法访问，因为组件尚未挂载。这类逻辑必须放到 onMounted。另外，注意 beforeDestroy 在 Vue 3 中已更名为 onBeforeUnmount，记得检查拼写，否则不会执行清理操作。

逻辑复用与提取：组合函数的设计

将原本通过 mixins 或高阶组件复用的逻辑，改为编写独立的组合函数（useXxx）。例如，原本的 mixin 中包含的数据、计算属性和方法，可以抽成一个返回响应式对象和函数的函数。组合函数内部使用 ref、reactive、onMounted 等 API，并可在多个组件中调用。注意：组合函数应在 setup 中调用，不能在其他异步回调中调用，否则会丢失响应性。另外，组合函数之间可以通过传参或返回值进行交互，避免了 mixin 的命名冲突问题。

设计组合函数时，通常返回一个对象，包含响应式状态和方法。如果函数需要依赖组件属性（如 props），可以通过参数传入，并用 toRefs 保持响应性。例如 const { count } = toRefs(props)。另外，组合函数内部如果有清理逻辑（如定时器），可以在函数内返回一个 onUnmounted 的调用，由调用方在组件中注册。

常见陷阱与调试

迁移后若遇到数据不更新或模板渲染异常，首先检查是否在 setup 中正确返回了所有需要在模板中使用的变量。其次，确认 reactive 包裹的对象是否被直接替换整个对象（如 state = newState），这会导致响应性丢失，应只修改对象的属性。对于异步获取的数据，确保在 onMounted 中赋值而非 setup 函数本身。另外，使用 watch 时注意回调中不能返回 undefined，否则第二次 watch 可能不会触发。建议使用 Vue Devtools 的 Composition API 选项卡来调试响应式变量。

调试时，可以在 setup 中打印 ref 变量，看到的是 RefImpl 对象，不是实际值；如果需要查看值，加上 .value。另外，如果 watch 回调返回 undefined，Vue 3 会认为没有变化，第二次相同的值变化时可能不会触发，可以显式返回一个 ID 或使用 flush: 'sync'。对于复杂场景，建议先在隔离环境中重现问题，避免在生产直接调试。

迁移过程不必追求一次完成，可以从一个无副作用的工具组件开始，逐步积累经验。如果遇到边界情况，可以查看官方迁移指南中的详细对比表。只要每个步骤都确认过改动前后的行为，整体风险是可控的。