1. 项目概述一次框架升级的深度实践最近在重构一个维护了三年多的后台管理系统技术栈是 Vue2 Element UI。随着业务模块越堆越多单个 .vue 文件动辄五六百行成了常态尤其是那些集成了复杂表单、数据表格和图表看板的页面。逻辑分散在data、methods、computed、watch各个区块里追踪一个功能相关的代码需要上下反复滚动维护和新增功能都变得异常痛苦。这促使我下定决心将项目升级到 Vue3并全面拥抱 Composition API。这不仅仅是一次简单的版本更新更像是对前端代码组织方式的一次彻底反思和重构。Vue3 带来的不仅仅是性能提升和更小的包体积其核心的 Composition API 从根本上改变了我们组织和复用逻辑的方式。从 Options API 到 Composition API 的演进远不止是语法糖的变化它代表着前端开发从“配置驱动”向“函数式组合”思维的深刻转变。这篇文章我将结合这次大规模迁移的真实经历为你拆解 Vue2 与 Vue3 在核心 API 设计上的本质区别分享实战中的升级策略、具体代码对比、遇到的深坑以及最终带来的开发体验提升无论你是正在考虑升级的 Vue2 老手还是想直接上手 Vue3 的新人都能从中找到直接的参考和答案。2. 核心设计哲学从“选项配置”到“逻辑组合”2.1 Options API清晰的结构与分散的逻辑Vue2 的 Options API 是其成功的关键之一。它通过定义一系列选项data,methods,computed,watch,lifecycle hooks来声明一个组件结构非常清晰对于初学者和小型项目来说上手极快。你不需要思考代码组织框架已经为你规划好了“房间”你只需要把对应的“家具”数据、方法放进对应的房间即可。// Vue2 Options API 示例一个用户查询组件 export default { name: UserSearch, data() { return { searchKeyword: , userList: [], loading: false, pagination: { page: 1, pageSize: 10, total: 0 } }; }, computed: { filteredUsers() { // 依赖于 searchKeyword 和 userList return this.userList.filter(user user.name.includes(this.searchKeyword) ); } }, watch: { searchKeyword(newVal) { // 关键词变化时重新搜索 if (newVal.trim() ! ) { this.debouncedSearch(); } }, pagination.page(newPage) { // 页码变化时加载数据 this.fetchUsers(); } }, methods: { async fetchUsers() { this.loading true; try { const params { keyword: this.searchKeyword, page: this.pagination.page, pageSize: this.pagination.pageSize }; const { data } await axios.get(/api/users, { params }); this.userList data.list; this.pagination.total data.total; } catch (error) { console.error(Fetch users failed:, error); } finally { this.loading false; } }, debouncedSearch: _.debounce(function() { this.pagination.page 1; // 重置页码 this.fetchUsers(); }, 500) }, mounted() { // 组件挂载时加载初始数据 this.fetchUsers(); } };这种模式的优点在于强制性的结构让组件的基本轮廓一目了然。但它的缺点在复杂组件中暴露无遗关注点分离是物理的而非逻辑的。上面这个简单的用户查询功能相关的代码关键词、加载状态、分页、获取数据的方法被强行拆分到了data、methods、computed、watch、mounted至少五个不同的区块中。当你要修改或理解“搜索”这个功能时你必须在文件里来回跳转。如果这个组件再增加一个“用户角色筛选”功能相关的变量和方法又会分散到这些区块文件会进一步膨胀逻辑关联性更加弱化。2.2 Composition API自由的组合与内聚的关注点Vue3 引入的 Composition API 的核心思想是将组件的逻辑关注点组织为可复用的函数。它不再强制你按选项分类代码而是允许你像写普通 JavaScript 函数一样将相关联的响应式数据、计算属性、方法和生命周期钩子组合在一起。它主要提供了两个核心函数ref和reactive用于创建响应式数据computed和watch用于派生状态和副作用以及onMounted、onUpdated等生命周期钩子函数。最重要的是你可以将任意一段逻辑例如上面的用户搜索封装到一个独立的函数中这个函数内部可以包含它所需的所有响应式状态和逻辑。// Vue3 Composition API 示例使用自定义 Hook 重构用户查询逻辑 import { ref, computed, watch, onMounted } from vue; import { debounce } from lodash-es; import axios from axios; // 将用户搜索逻辑抽离为一个可复用的组合式函数 function useUserSearch() { // 1. 定义响应式状态逻辑相关的数据放在一起 const searchKeyword ref(); const userList ref([]); const loading ref(false); const pagination reactive({ page: 1, pageSize: 10, total: 0 }); // 2. 定义计算属性 const filteredUsers computed(() { return userList.value.filter(user user.name.includes(searchKeyword.value) ); }); // 3. 定义方法 const fetchUsers async () { loading.value true; try { const params { keyword: searchKeyword.value, page: pagination.page, pageSize: pagination.pageSize }; const { data } await axios.get(/api/users, { params }); userList.value data.list; pagination.total data.total; } catch (error) { console.error(Fetch users failed:, error); } finally { loading.value false; } }; // 4. 定义防抖搜索函数 const debouncedSearch debounce(() { pagination.page 1; fetchUsers(); }, 500); // 5. 定义侦听器 watch(searchKeyword, (newVal) { if (newVal.trim() ! ) { debouncedSearch(); } }); watch(() pagination.page, () { fetchUsers(); }); // 6. 生命周期钩子如果需要 onMounted(() { fetchUsers(); }); // 7. 返回所有需要暴露给组件的内容 return { searchKeyword, userList, loading, pagination, filteredUsers, fetchUsers }; } // 在组件中使用 export default { setup() { // 直接调用组合式函数获得所有相关的状态和方法 const { searchKeyword, userList, loading, pagination, filteredUsers, fetchUsers } useUserSearch(); // 组件可能还有其他独立的逻辑... // const { ... } useOtherLogic(); return { searchKeyword, userList, loading, pagination, filteredUsers, fetchUsers }; } };这种模式的革命性在于useUserSearch这个函数就是一个完整的、自包含的逻辑单元。如果你想在另一个组件中也实现用户搜索直接导入并调用这个函数即可实现了真正的逻辑复用。在组件内部通过调用不同的组合式函数你可以像搭积木一样组合功能每个功能块的代码都紧密内聚大大提升了代码的可读性和可维护性。注意很多初学者会误以为setup函数只是把 Options API 的代码挪了个位置。关键在于你要学会根据“功能”或“关注点”来组织代码将相关的ref、computed、watch、method封装在一起而不是根据“类型”把所有ref放一堆所有computed放另一堆。3. 响应式系统的根本性变革3.1 Vue2 的响应式基于 Object.defineProperty 的劫持Vue2 的响应式核心是Object.defineProperty。它通过递归遍历数据对象对每个属性进行getter和setter的劫持来实现依赖收集和派发更新。这种方式存在几个固有的限制无法检测属性的添加或删除你必须使用Vue.set或Vue.delete来确保新属性是响应式的。// Vue2 中 this.someObject.newProperty value; // 不是响应式的 Vue.set(this.someObject, newProperty, value); // 正确做法数组的变异直接通过索引设置数组项 (this.items[index] newValue) 或修改数组长度不会被检测到。Vue2 重写了数组的push,pop,shift,unshift,splice,sort,reverse七个方法来实现响应式。初始化性能对于深层嵌套的大对象递归遍历和转换每个属性在初始化时有性能开销。3.2 Vue3 的响应式基于 Proxy 的代理Vue3 使用了 ES6 的Proxy来重写响应式系统。Proxy可以拦截对象的基本操作包括属性读取、设置、删除、in操作符等提供了更强大和全面的拦截能力。import { reactive } from vue; const state reactive({ count: 0, user: { name: Alice, details: { age: 25 } }, hobbies: [reading, coding] }); // 1. 动态添加属性是响应式的 state.newProperty I am reactive!; // 2. 直接通过索引修改数组是响应式的 state.hobbies[0] gaming; // 3. 使用 delete 操作符删除属性也是响应式的 delete state.user.details.age;Proxy 带来的优势全面的拦截解决了 Vue2 中对象增删属性和数组索引操作的非响应式问题。更好的性能Proxy是“懒代理”的只有在访问某个嵌套属性时才会递归将其转换为响应式初始化性能更优。支持 Map、Set 等集合类型Vue3 可以原生地使这些 ES6 集合类型变为响应式。ref与reactive的选用reactive用于创建对象或数组的响应式代理。它返回一个代理对象访问和修改属性直接使用.操作符。ref用于创建对任意值的响应式引用。它返回一个具有.value属性的对象。在模板中或作为reactive对象的属性时Vue 会自动解包.value。const count ref(0); // 基本类型用 ref const state reactive({ // 对象用 reactive count, // 这里会自动解包模板中直接 state.count 即可 name: ref(Vue3) // 嵌套的 ref 也会自动解包 }); // 在 JavaScript 中操作 count.value; // ref 需要 .value state.name New Name; // reactive 属性直接赋值实操心得一个简单的选用原则——基本类型string,number,boolean,null,undefined用ref对象类型Object,Array,Map,Set用reactive。在组合式函数中为了保持一致性我倾向于全部使用ref因为它的.value语法明确告诉你这是一个响应式引用并且在函数返回时结构也更清晰。4. 生命周期钩子的映射与新增生命周期钩子在 Composition API 中是以函数的形式提供的命名上加了on前缀逻辑上基本可以与 Options API 一一对应。Vue2 Options APIVue3 Composition API (insidesetup)触发时机beforeCreateNot Needed组件实例初始化之前。在setup中此时响应式系统尚未建立setup函数本身在此阶段执行。createdNot Needed组件实例创建完成响应式数据已初始化。setup函数在此阶段执行完毕。beforeMountonBeforeMount挂载开始之前模板编译/渲染函数首次被调用。mountedonMounted组件挂载到 DOM 后。可以安全访问 DOM 元素。beforeUpdateonBeforeUpdate响应式数据变化虚拟 DOM 重新渲染和打补丁之前。updatedonUpdated虚拟 DOM 重新渲染和打补丁之后。避免在此钩子中修改状态可能导致无限循环。beforeDestroyonBeforeUnmount组件实例销毁之前。destroyedonUnmounted组件实例销毁后。清理定时器、取消事件监听、解绑全局监听器等操作应在此进行。errorCapturedonErrorCaptured捕获后代组件传递的错误时调用。最重要的变化beforeCreate和created在 Composition API 中不再需要。因为setup函数就是在组件创建阶段运行的所有原本放在created里的初始化逻辑现在直接放在setup函数顶部即可。销毁钩子更名为onBeforeUnmount和onUnmounted语义更清晰。新增了调试钩子onRenderTracked调试渲染依赖跟踪和onRenderTriggered调试渲染触发在开发模式下帮助分析性能问题。使用示例import { onMounted, onUnmounted, ref } from vue; export default { setup() { const intervalId ref(null); const count ref(0); onMounted(() { console.log(组件已挂载开始计时器); intervalId.value setInterval(() { count.value; }, 1000); }); onUnmounted(() { console.log(组件即将销毁清理计时器); if (intervalId.value) { clearInterval(intervalId.value); } }); return { count }; } };注意事项Composition API 的生命周期钩子函数是同步注册的。务必在setup函数中同步调用它们而不能放在异步回调里。否则钩子可能不会按预期工作。5. 逻辑复用模式的颠覆从 Mixins/Scoped Slots 到 Composables5.1 Vue2 的逻辑复用之痛在 Vue2 中跨组件逻辑复用主要依靠Mixins和作用域插槽 (Scoped Slots)。Mixins将一组组件选项合并到目标组件中。问题非常突出命名冲突多个 Mixin 或与组件本身定义了同名的数据/方法后者会覆盖前者调试困难。隐式依赖Mixin 使用了哪些属性、注入了哪些属性不清晰数据来源模糊。可维护性差随着项目变大Mixins 之间的关系网会变得极其复杂被称为“滚雪球式”的复用。作用域插槽通过插槽传递数据和模板可以实现更灵活的逻辑复用但通常用于 UI 结构的复用对于纯 JavaScript 逻辑的复用显得笨重。5.2 Vue3 Composables函数式的完美解决方案Composition API 催生了Composables组合式函数的模式。一个 Composable 就是一个利用 Vue 的响应式 API 来封装和复用有状态逻辑的 JavaScript 函数。上面useUserSearch就是一个典型的 Composable。它的优势是压倒性的显式依赖函数参数和返回值清晰定义了输入和输出依赖关系一目了然。命名空间隔离通过解构赋值你可以自由重命名返回的状态彻底避免命名冲突。setup() { const { list: userList, search: searchUser } useUserSearch(); const { list: productList, search: searchProduct } useProductSearch(); // 清晰无冲突 }可组合性Composables 之间可以相互调用组合出更复杂的功能像搭积木一样。function usePaginatedList(fetchApi) { // 封装分页逻辑 const pagination reactive({ page: 1, pageSize: 10, total: 0 }); const loadData async () { /* ... */ }; return { pagination, loadData }; } function useSearch(loadData) { // 封装搜索逻辑 const keyword ref(); watch(keyword, () loadData()); return { keyword }; } function useUserManagement() { // 组合使用 const { pagination, loadData } usePaginatedList(fetchUsers); const { keyword } useSearch(loadData); // ... 其他用户管理逻辑 return { pagination, keyword, loadData }; }TypeScript 友好纯函数加上明确的输入输出能获得完美的类型推断。实战中我将旧项目中的 Mixins 逐一重构成了 Composables。例如一个用于处理表单验证和提交的formMixin被重构成了useFormValidation和useFormSubmit。不仅代码更清晰而且在新的组件中复用起来极其简单和安全。6. 迁移实战策略、步骤与常见坑位将大型 Vue2 项目升级到 Vue3 并非一蹴而就。我采用的是渐进式迁移策略。6.1 升级前准备与策略选择版本升级首先确保 Vue2 项目使用较新的版本2.7因为它包含了部分 Vue3 兼容的 API如defineComponent 部分 Composition API 的向后移植。同时升级 Vue CLI 或 Vite 等构建工具。依赖检查使用vue-compat构建或社区工具如vue2-upgrade检查第三方库特别是 UI 库如 Element UI、Vuetify对 Vue3 的支持情况。这是最大的风险点。我当时的项目重度依赖 Element UI而它的 Vue3 版本Element Plus存在一些 Breaking Changes需要预留大量时间进行组件替换和样式调整。策略选择一次性升级适合中小型项目或依赖生态已完全就绪的项目。关闭旧版本全体迁移。渐进式升级适合大型、复杂的生产项目。这是我们的选择。我们利用 Vue3 的vue/compat一个构建时兼容版本让 Vue3 运行时以近乎兼容的方式运行 Vue2 代码。然后在新开发的模块或重构的旧模块中直接使用 Vue3 和 Composition API与旧的 Options API 组件共存。6.2 具体代码迁移示例与差异点1. 组件定义与导入// Vue2 import Vue from vue; export default { name: MyComponent, // ... options } // Vue3 (推荐使用 defineComponent 以获得更好的 TypeScript 支持) import { defineComponent } from vue; export default defineComponent({ name: MyComponent, // 可以使用 Options API 或 setup 函数 setup() { // Composition API 逻辑 } });2. 事件总线Event Bus的替代Vue2 中常用的new Vue()作为事件总线在 Vue3 中不再推荐。替代方案使用mitt或tiny-emitter等第三方库轻量且好用。使用provide/inject进行跨层级组件通信。使用 Pinia/Vuex 状态管理。3. 过滤器Filters的移除Vue3 移除了过滤器。替代方案是使用方法methods或计算属性computed。// Vue2 {{ price | currency }} // Vue3 {{ formatCurrency(price) }} // 在 setup 中 const formatCurrency (value) { return $ value.toFixed(2); };4.v-model的变更Vue2 中v-model是valueprop 和input事件的语法糖。Vue3 中改为modelValueprop 和update:modelValue事件并支持多个v-model绑定。!-- Vue2 子组件 -- script export default { props: [value], methods: { updateValue(newVal) { this.$emit(input, newVal); } } } /script !-- Vue3 子组件 -- script setup defineProps([modelValue]); defineEmits([update:modelValue]); const updateValue (newVal) { emit(update:modelValue, newVal); } /script !-- 父组件使用 -- !-- Vue2: MyInput v-modeltext / -- !-- Vue3: MyInput v-modeltext / -- !-- Vue3 多个 v-model: MyComponent v-model:titletitle v-model:contentcontent / --5. 异步组件定义// Vue2 const AsyncComponent () import(./MyComponent.vue); // Vue3 - 使用 defineAsyncComponent import { defineAsyncComponent } from vue; const AsyncComponent defineAsyncComponent(() import(./MyComponent.vue) );6.3 迁移过程中的典型问题与解决方案问题一第三方库不兼容这是最普遍的问题。我们的解决方案是寻找官方支持的 Vue3 版本如 Element Plus 替代 Element UI。寻找社区维护的 Vue3 兼容版本。如果以上都没有则评估该库的重要性。如果是核心功能考虑自己封装一个简单的替代实现或者寻找其他 Vue3 兼容的库。问题二this上下文丢失在 Composition API 的setup函数中没有this。所有组件实例的 property如$router,$store都需要通过新的 API 获取。import { useRouter, useStore } from vue-router; // 假设使用 Vue Router 4 import { useStore } from vuex; // 假设使用 Vuex 4 setup() { const router useRouter(); const store useStore(); // 访问路由或状态 console.log(store.state.someModule); router.push(/home); }问题三响应式数组操作习惯在 Vue2 中直接修改数组索引或长度不生效必须用变异方法或Vue.set。在 Vue3 中由于使用 Proxy直接修改是生效的。但需要注意直接替换整个数组引用仍然是触发响应式更新的最可靠方式尤其是在涉及复杂计算或依赖跟踪时。// Vue3 中以下两种方式都有效但推荐后者用于复杂场景 state.items[0] newItem; // 有效 state.items [...state.items]; // 更明确地触发更新通过替换引用问题四生命周期钩子调用时机确保在setup中同步注册生命周期钩子。不要在异步代码块如setTimeout或Promise.then内部调用onMounted等。7. 性能与开发体验的直观提升7.1 性能优化更小的体积Vue3 通过更好的 Tree-shaking摇树优化和模块化设计核心运行时体积比 Vue2 小约 40%。更快的渲染基于 Proxy 的响应式系统初始化更快且编译器优化生成了更高效的虚拟 DOM 渲染函数。更好的更新性能Vue3 的编译器会生成带有更新类型标记的虚拟 DOM在 diff 算法时可以跳过静态节点提升更新效率。7.2 开发体验飞跃TypeScript 集成Vue3 本身用 TypeScript 重写提供了完美的类型推导。使用script setup langts语法开发体验堪比纯 TypeScript 项目智能提示和类型安全极大提升。更好的调试工具Vue DevTools 对 Vue3 和 Composition API 提供了专门的支持可以清晰地查看组件层级、响应式数据、以及 Composable 的调用栈。更灵活的代码组织Composition API 让代码组织不再受框架选项的约束可以按照业务逻辑而非技术关注点来写代码这对于大型项目和团队协作是质的提升。8. 总结与个人建议从 Vue2 的 Options API 到 Vue3 的 Composition API是一次从“约定大于配置”到“组合优于继承”的范式转移。初期学习 Composition API 可能会觉得有些抽象尤其是.value的操作和思维模式的转变。但一旦适应你会发现它带来的代码可读性、可维护性和可复用性是 Options API 难以企及的。对于还在 Vue2 的项目如果你的项目稳定且近期无重大改动不一定需要立即升级。但如果是新启动的项目强烈建议直接从 Vue3 开始。对于准备升级的项目充分评估仔细检查你的依赖生态特别是 UI 组件库。制定计划采用渐进式迁移利用vue/compat桥接。团队学习确保团队成员对 Composition API 有基本了解可以先在新模块中小范围试用。逐步重构不要试图一次性重写所有组件。在修改 bug 或添加新功能时顺势将相关组件重构为 Composition API。我个人最深刻的体会是Composition API 更像是在写纯粹的 JavaScript。它把 Vue 的响应式能力以函数的形式提供给你让你可以像组织普通工具函数一样组织你的组件逻辑。这种自由度和灵活性使得复杂前端应用的代码结构终于可以变得清晰和可预测。虽然迁移过程有阵痛但看到重构后那些内聚、独立、易于测试的组合式函数以及在新功能开发时行云流水般的逻辑复用你会觉得这一切都是值得的。最后一个小技巧在重构初期可以尝试先在一个组件内将某个独立的逻辑块比如一个表单验证、一个数据获取抽离成一个独立的useXxx函数即使暂时不复用也能立刻感受到代码组织的改善。
Vue3 Composition API 实战：从 Options API 到逻辑复用的范式迁移
1. 项目概述一次框架升级的深度实践最近在重构一个维护了三年多的后台管理系统技术栈是 Vue2 Element UI。随着业务模块越堆越多单个 .vue 文件动辄五六百行成了常态尤其是那些集成了复杂表单、数据表格和图表看板的页面。逻辑分散在data、methods、computed、watch各个区块里追踪一个功能相关的代码需要上下反复滚动维护和新增功能都变得异常痛苦。这促使我下定决心将项目升级到 Vue3并全面拥抱 Composition API。这不仅仅是一次简单的版本更新更像是对前端代码组织方式的一次彻底反思和重构。Vue3 带来的不仅仅是性能提升和更小的包体积其核心的 Composition API 从根本上改变了我们组织和复用逻辑的方式。从 Options API 到 Composition API 的演进远不止是语法糖的变化它代表着前端开发从“配置驱动”向“函数式组合”思维的深刻转变。这篇文章我将结合这次大规模迁移的真实经历为你拆解 Vue2 与 Vue3 在核心 API 设计上的本质区别分享实战中的升级策略、具体代码对比、遇到的深坑以及最终带来的开发体验提升无论你是正在考虑升级的 Vue2 老手还是想直接上手 Vue3 的新人都能从中找到直接的参考和答案。2. 核心设计哲学从“选项配置”到“逻辑组合”2.1 Options API清晰的结构与分散的逻辑Vue2 的 Options API 是其成功的关键之一。它通过定义一系列选项data,methods,computed,watch,lifecycle hooks来声明一个组件结构非常清晰对于初学者和小型项目来说上手极快。你不需要思考代码组织框架已经为你规划好了“房间”你只需要把对应的“家具”数据、方法放进对应的房间即可。// Vue2 Options API 示例一个用户查询组件 export default { name: UserSearch, data() { return { searchKeyword: , userList: [], loading: false, pagination: { page: 1, pageSize: 10, total: 0 } }; }, computed: { filteredUsers() { // 依赖于 searchKeyword 和 userList return this.userList.filter(user user.name.includes(this.searchKeyword) ); } }, watch: { searchKeyword(newVal) { // 关键词变化时重新搜索 if (newVal.trim() ! ) { this.debouncedSearch(); } }, pagination.page(newPage) { // 页码变化时加载数据 this.fetchUsers(); } }, methods: { async fetchUsers() { this.loading true; try { const params { keyword: this.searchKeyword, page: this.pagination.page, pageSize: this.pagination.pageSize }; const { data } await axios.get(/api/users, { params }); this.userList data.list; this.pagination.total data.total; } catch (error) { console.error(Fetch users failed:, error); } finally { this.loading false; } }, debouncedSearch: _.debounce(function() { this.pagination.page 1; // 重置页码 this.fetchUsers(); }, 500) }, mounted() { // 组件挂载时加载初始数据 this.fetchUsers(); } };这种模式的优点在于强制性的结构让组件的基本轮廓一目了然。但它的缺点在复杂组件中暴露无遗关注点分离是物理的而非逻辑的。上面这个简单的用户查询功能相关的代码关键词、加载状态、分页、获取数据的方法被强行拆分到了data、methods、computed、watch、mounted至少五个不同的区块中。当你要修改或理解“搜索”这个功能时你必须在文件里来回跳转。如果这个组件再增加一个“用户角色筛选”功能相关的变量和方法又会分散到这些区块文件会进一步膨胀逻辑关联性更加弱化。2.2 Composition API自由的组合与内聚的关注点Vue3 引入的 Composition API 的核心思想是将组件的逻辑关注点组织为可复用的函数。它不再强制你按选项分类代码而是允许你像写普通 JavaScript 函数一样将相关联的响应式数据、计算属性、方法和生命周期钩子组合在一起。它主要提供了两个核心函数ref和reactive用于创建响应式数据computed和watch用于派生状态和副作用以及onMounted、onUpdated等生命周期钩子函数。最重要的是你可以将任意一段逻辑例如上面的用户搜索封装到一个独立的函数中这个函数内部可以包含它所需的所有响应式状态和逻辑。// Vue3 Composition API 示例使用自定义 Hook 重构用户查询逻辑 import { ref, computed, watch, onMounted } from vue; import { debounce } from lodash-es; import axios from axios; // 将用户搜索逻辑抽离为一个可复用的组合式函数 function useUserSearch() { // 1. 定义响应式状态逻辑相关的数据放在一起 const searchKeyword ref(); const userList ref([]); const loading ref(false); const pagination reactive({ page: 1, pageSize: 10, total: 0 }); // 2. 定义计算属性 const filteredUsers computed(() { return userList.value.filter(user user.name.includes(searchKeyword.value) ); }); // 3. 定义方法 const fetchUsers async () { loading.value true; try { const params { keyword: searchKeyword.value, page: pagination.page, pageSize: pagination.pageSize }; const { data } await axios.get(/api/users, { params }); userList.value data.list; pagination.total data.total; } catch (error) { console.error(Fetch users failed:, error); } finally { loading.value false; } }; // 4. 定义防抖搜索函数 const debouncedSearch debounce(() { pagination.page 1; fetchUsers(); }, 500); // 5. 定义侦听器 watch(searchKeyword, (newVal) { if (newVal.trim() ! ) { debouncedSearch(); } }); watch(() pagination.page, () { fetchUsers(); }); // 6. 生命周期钩子如果需要 onMounted(() { fetchUsers(); }); // 7. 返回所有需要暴露给组件的内容 return { searchKeyword, userList, loading, pagination, filteredUsers, fetchUsers }; } // 在组件中使用 export default { setup() { // 直接调用组合式函数获得所有相关的状态和方法 const { searchKeyword, userList, loading, pagination, filteredUsers, fetchUsers } useUserSearch(); // 组件可能还有其他独立的逻辑... // const { ... } useOtherLogic(); return { searchKeyword, userList, loading, pagination, filteredUsers, fetchUsers }; } };这种模式的革命性在于useUserSearch这个函数就是一个完整的、自包含的逻辑单元。如果你想在另一个组件中也实现用户搜索直接导入并调用这个函数即可实现了真正的逻辑复用。在组件内部通过调用不同的组合式函数你可以像搭积木一样组合功能每个功能块的代码都紧密内聚大大提升了代码的可读性和可维护性。注意很多初学者会误以为setup函数只是把 Options API 的代码挪了个位置。关键在于你要学会根据“功能”或“关注点”来组织代码将相关的ref、computed、watch、method封装在一起而不是根据“类型”把所有ref放一堆所有computed放另一堆。3. 响应式系统的根本性变革3.1 Vue2 的响应式基于 Object.defineProperty 的劫持Vue2 的响应式核心是Object.defineProperty。它通过递归遍历数据对象对每个属性进行getter和setter的劫持来实现依赖收集和派发更新。这种方式存在几个固有的限制无法检测属性的添加或删除你必须使用Vue.set或Vue.delete来确保新属性是响应式的。// Vue2 中 this.someObject.newProperty value; // 不是响应式的 Vue.set(this.someObject, newProperty, value); // 正确做法数组的变异直接通过索引设置数组项 (this.items[index] newValue) 或修改数组长度不会被检测到。Vue2 重写了数组的push,pop,shift,unshift,splice,sort,reverse七个方法来实现响应式。初始化性能对于深层嵌套的大对象递归遍历和转换每个属性在初始化时有性能开销。3.2 Vue3 的响应式基于 Proxy 的代理Vue3 使用了 ES6 的Proxy来重写响应式系统。Proxy可以拦截对象的基本操作包括属性读取、设置、删除、in操作符等提供了更强大和全面的拦截能力。import { reactive } from vue; const state reactive({ count: 0, user: { name: Alice, details: { age: 25 } }, hobbies: [reading, coding] }); // 1. 动态添加属性是响应式的 state.newProperty I am reactive!; // 2. 直接通过索引修改数组是响应式的 state.hobbies[0] gaming; // 3. 使用 delete 操作符删除属性也是响应式的 delete state.user.details.age;Proxy 带来的优势全面的拦截解决了 Vue2 中对象增删属性和数组索引操作的非响应式问题。更好的性能Proxy是“懒代理”的只有在访问某个嵌套属性时才会递归将其转换为响应式初始化性能更优。支持 Map、Set 等集合类型Vue3 可以原生地使这些 ES6 集合类型变为响应式。ref与reactive的选用reactive用于创建对象或数组的响应式代理。它返回一个代理对象访问和修改属性直接使用.操作符。ref用于创建对任意值的响应式引用。它返回一个具有.value属性的对象。在模板中或作为reactive对象的属性时Vue 会自动解包.value。const count ref(0); // 基本类型用 ref const state reactive({ // 对象用 reactive count, // 这里会自动解包模板中直接 state.count 即可 name: ref(Vue3) // 嵌套的 ref 也会自动解包 }); // 在 JavaScript 中操作 count.value; // ref 需要 .value state.name New Name; // reactive 属性直接赋值实操心得一个简单的选用原则——基本类型string,number,boolean,null,undefined用ref对象类型Object,Array,Map,Set用reactive。在组合式函数中为了保持一致性我倾向于全部使用ref因为它的.value语法明确告诉你这是一个响应式引用并且在函数返回时结构也更清晰。4. 生命周期钩子的映射与新增生命周期钩子在 Composition API 中是以函数的形式提供的命名上加了on前缀逻辑上基本可以与 Options API 一一对应。Vue2 Options APIVue3 Composition API (insidesetup)触发时机beforeCreateNot Needed组件实例初始化之前。在setup中此时响应式系统尚未建立setup函数本身在此阶段执行。createdNot Needed组件实例创建完成响应式数据已初始化。setup函数在此阶段执行完毕。beforeMountonBeforeMount挂载开始之前模板编译/渲染函数首次被调用。mountedonMounted组件挂载到 DOM 后。可以安全访问 DOM 元素。beforeUpdateonBeforeUpdate响应式数据变化虚拟 DOM 重新渲染和打补丁之前。updatedonUpdated虚拟 DOM 重新渲染和打补丁之后。避免在此钩子中修改状态可能导致无限循环。beforeDestroyonBeforeUnmount组件实例销毁之前。destroyedonUnmounted组件实例销毁后。清理定时器、取消事件监听、解绑全局监听器等操作应在此进行。errorCapturedonErrorCaptured捕获后代组件传递的错误时调用。最重要的变化beforeCreate和created在 Composition API 中不再需要。因为setup函数就是在组件创建阶段运行的所有原本放在created里的初始化逻辑现在直接放在setup函数顶部即可。销毁钩子更名为onBeforeUnmount和onUnmounted语义更清晰。新增了调试钩子onRenderTracked调试渲染依赖跟踪和onRenderTriggered调试渲染触发在开发模式下帮助分析性能问题。使用示例import { onMounted, onUnmounted, ref } from vue; export default { setup() { const intervalId ref(null); const count ref(0); onMounted(() { console.log(组件已挂载开始计时器); intervalId.value setInterval(() { count.value; }, 1000); }); onUnmounted(() { console.log(组件即将销毁清理计时器); if (intervalId.value) { clearInterval(intervalId.value); } }); return { count }; } };注意事项Composition API 的生命周期钩子函数是同步注册的。务必在setup函数中同步调用它们而不能放在异步回调里。否则钩子可能不会按预期工作。5. 逻辑复用模式的颠覆从 Mixins/Scoped Slots 到 Composables5.1 Vue2 的逻辑复用之痛在 Vue2 中跨组件逻辑复用主要依靠Mixins和作用域插槽 (Scoped Slots)。Mixins将一组组件选项合并到目标组件中。问题非常突出命名冲突多个 Mixin 或与组件本身定义了同名的数据/方法后者会覆盖前者调试困难。隐式依赖Mixin 使用了哪些属性、注入了哪些属性不清晰数据来源模糊。可维护性差随着项目变大Mixins 之间的关系网会变得极其复杂被称为“滚雪球式”的复用。作用域插槽通过插槽传递数据和模板可以实现更灵活的逻辑复用但通常用于 UI 结构的复用对于纯 JavaScript 逻辑的复用显得笨重。5.2 Vue3 Composables函数式的完美解决方案Composition API 催生了Composables组合式函数的模式。一个 Composable 就是一个利用 Vue 的响应式 API 来封装和复用有状态逻辑的 JavaScript 函数。上面useUserSearch就是一个典型的 Composable。它的优势是压倒性的显式依赖函数参数和返回值清晰定义了输入和输出依赖关系一目了然。命名空间隔离通过解构赋值你可以自由重命名返回的状态彻底避免命名冲突。setup() { const { list: userList, search: searchUser } useUserSearch(); const { list: productList, search: searchProduct } useProductSearch(); // 清晰无冲突 }可组合性Composables 之间可以相互调用组合出更复杂的功能像搭积木一样。function usePaginatedList(fetchApi) { // 封装分页逻辑 const pagination reactive({ page: 1, pageSize: 10, total: 0 }); const loadData async () { /* ... */ }; return { pagination, loadData }; } function useSearch(loadData) { // 封装搜索逻辑 const keyword ref(); watch(keyword, () loadData()); return { keyword }; } function useUserManagement() { // 组合使用 const { pagination, loadData } usePaginatedList(fetchUsers); const { keyword } useSearch(loadData); // ... 其他用户管理逻辑 return { pagination, keyword, loadData }; }TypeScript 友好纯函数加上明确的输入输出能获得完美的类型推断。实战中我将旧项目中的 Mixins 逐一重构成了 Composables。例如一个用于处理表单验证和提交的formMixin被重构成了useFormValidation和useFormSubmit。不仅代码更清晰而且在新的组件中复用起来极其简单和安全。6. 迁移实战策略、步骤与常见坑位将大型 Vue2 项目升级到 Vue3 并非一蹴而就。我采用的是渐进式迁移策略。6.1 升级前准备与策略选择版本升级首先确保 Vue2 项目使用较新的版本2.7因为它包含了部分 Vue3 兼容的 API如defineComponent 部分 Composition API 的向后移植。同时升级 Vue CLI 或 Vite 等构建工具。依赖检查使用vue-compat构建或社区工具如vue2-upgrade检查第三方库特别是 UI 库如 Element UI、Vuetify对 Vue3 的支持情况。这是最大的风险点。我当时的项目重度依赖 Element UI而它的 Vue3 版本Element Plus存在一些 Breaking Changes需要预留大量时间进行组件替换和样式调整。策略选择一次性升级适合中小型项目或依赖生态已完全就绪的项目。关闭旧版本全体迁移。渐进式升级适合大型、复杂的生产项目。这是我们的选择。我们利用 Vue3 的vue/compat一个构建时兼容版本让 Vue3 运行时以近乎兼容的方式运行 Vue2 代码。然后在新开发的模块或重构的旧模块中直接使用 Vue3 和 Composition API与旧的 Options API 组件共存。6.2 具体代码迁移示例与差异点1. 组件定义与导入// Vue2 import Vue from vue; export default { name: MyComponent, // ... options } // Vue3 (推荐使用 defineComponent 以获得更好的 TypeScript 支持) import { defineComponent } from vue; export default defineComponent({ name: MyComponent, // 可以使用 Options API 或 setup 函数 setup() { // Composition API 逻辑 } });2. 事件总线Event Bus的替代Vue2 中常用的new Vue()作为事件总线在 Vue3 中不再推荐。替代方案使用mitt或tiny-emitter等第三方库轻量且好用。使用provide/inject进行跨层级组件通信。使用 Pinia/Vuex 状态管理。3. 过滤器Filters的移除Vue3 移除了过滤器。替代方案是使用方法methods或计算属性computed。// Vue2 {{ price | currency }} // Vue3 {{ formatCurrency(price) }} // 在 setup 中 const formatCurrency (value) { return $ value.toFixed(2); };4.v-model的变更Vue2 中v-model是valueprop 和input事件的语法糖。Vue3 中改为modelValueprop 和update:modelValue事件并支持多个v-model绑定。!-- Vue2 子组件 -- script export default { props: [value], methods: { updateValue(newVal) { this.$emit(input, newVal); } } } /script !-- Vue3 子组件 -- script setup defineProps([modelValue]); defineEmits([update:modelValue]); const updateValue (newVal) { emit(update:modelValue, newVal); } /script !-- 父组件使用 -- !-- Vue2: MyInput v-modeltext / -- !-- Vue3: MyInput v-modeltext / -- !-- Vue3 多个 v-model: MyComponent v-model:titletitle v-model:contentcontent / --5. 异步组件定义// Vue2 const AsyncComponent () import(./MyComponent.vue); // Vue3 - 使用 defineAsyncComponent import { defineAsyncComponent } from vue; const AsyncComponent defineAsyncComponent(() import(./MyComponent.vue) );6.3 迁移过程中的典型问题与解决方案问题一第三方库不兼容这是最普遍的问题。我们的解决方案是寻找官方支持的 Vue3 版本如 Element Plus 替代 Element UI。寻找社区维护的 Vue3 兼容版本。如果以上都没有则评估该库的重要性。如果是核心功能考虑自己封装一个简单的替代实现或者寻找其他 Vue3 兼容的库。问题二this上下文丢失在 Composition API 的setup函数中没有this。所有组件实例的 property如$router,$store都需要通过新的 API 获取。import { useRouter, useStore } from vue-router; // 假设使用 Vue Router 4 import { useStore } from vuex; // 假设使用 Vuex 4 setup() { const router useRouter(); const store useStore(); // 访问路由或状态 console.log(store.state.someModule); router.push(/home); }问题三响应式数组操作习惯在 Vue2 中直接修改数组索引或长度不生效必须用变异方法或Vue.set。在 Vue3 中由于使用 Proxy直接修改是生效的。但需要注意直接替换整个数组引用仍然是触发响应式更新的最可靠方式尤其是在涉及复杂计算或依赖跟踪时。// Vue3 中以下两种方式都有效但推荐后者用于复杂场景 state.items[0] newItem; // 有效 state.items [...state.items]; // 更明确地触发更新通过替换引用问题四生命周期钩子调用时机确保在setup中同步注册生命周期钩子。不要在异步代码块如setTimeout或Promise.then内部调用onMounted等。7. 性能与开发体验的直观提升7.1 性能优化更小的体积Vue3 通过更好的 Tree-shaking摇树优化和模块化设计核心运行时体积比 Vue2 小约 40%。更快的渲染基于 Proxy 的响应式系统初始化更快且编译器优化生成了更高效的虚拟 DOM 渲染函数。更好的更新性能Vue3 的编译器会生成带有更新类型标记的虚拟 DOM在 diff 算法时可以跳过静态节点提升更新效率。7.2 开发体验飞跃TypeScript 集成Vue3 本身用 TypeScript 重写提供了完美的类型推导。使用script setup langts语法开发体验堪比纯 TypeScript 项目智能提示和类型安全极大提升。更好的调试工具Vue DevTools 对 Vue3 和 Composition API 提供了专门的支持可以清晰地查看组件层级、响应式数据、以及 Composable 的调用栈。更灵活的代码组织Composition API 让代码组织不再受框架选项的约束可以按照业务逻辑而非技术关注点来写代码这对于大型项目和团队协作是质的提升。8. 总结与个人建议从 Vue2 的 Options API 到 Vue3 的 Composition API是一次从“约定大于配置”到“组合优于继承”的范式转移。初期学习 Composition API 可能会觉得有些抽象尤其是.value的操作和思维模式的转变。但一旦适应你会发现它带来的代码可读性、可维护性和可复用性是 Options API 难以企及的。对于还在 Vue2 的项目如果你的项目稳定且近期无重大改动不一定需要立即升级。但如果是新启动的项目强烈建议直接从 Vue3 开始。对于准备升级的项目充分评估仔细检查你的依赖生态特别是 UI 组件库。制定计划采用渐进式迁移利用vue/compat桥接。团队学习确保团队成员对 Composition API 有基本了解可以先在新模块中小范围试用。逐步重构不要试图一次性重写所有组件。在修改 bug 或添加新功能时顺势将相关组件重构为 Composition API。我个人最深刻的体会是Composition API 更像是在写纯粹的 JavaScript。它把 Vue 的响应式能力以函数的形式提供给你让你可以像组织普通工具函数一样组织你的组件逻辑。这种自由度和灵活性使得复杂前端应用的代码结构终于可以变得清晰和可预测。虽然迁移过程有阵痛但看到重构后那些内聚、独立、易于测试的组合式函数以及在新功能开发时行云流水般的逻辑复用你会觉得这一切都是值得的。最后一个小技巧在重构初期可以尝试先在一个组件内将某个独立的逻辑块比如一个表单验证、一个数据获取抽离成一个独立的useXxx函数即使暂时不复用也能立刻感受到代码组织的改善。