上周帮团队review一个五年多的Vue2老项目有个支付结果页的代码让我印象很深data里躺着二十几个字段methods里四五个业务块互相穿插调用computed里塞了七八个派生状态watch还监听了好几个token相关的字段。整个组件两千多行但真正要改一个小需求时根本不敢动——因为同一个功能的代码被拆到了五个不同的选项块里。说实话这种状态在2026年已经很难自洽了。Vue官方在Vue 3早就把组合式APIComposition API作为默认推荐生态里主流组件库、后台框架、面试题也都在围绕它转可我发现身边还是有不少人习惯性写着Options API。这篇文章我想从一线开发者的视角把组合式API到底解决了什么、迁移时怎么下手、以及哪些场景其实可以继续用Options API一次性说透。1. 先别急着站队Options API到底输在哪里1.1 代码组织按选项划分而不是按功能划分很多人觉得Options API挺好用的因为data、methods、computed这些选项结构清晰一看就知道哪里放数据、哪里放方法。但问题恰恰出在这个“清晰”上——它按类型组织代码而不是按功能组织代码。举个例子一个典型的订单列表页往往同时包含这些逻辑搜索表单的数据和提交方法列表数据的拉取和分页多选行的状态管理导出Excel的组装逻辑WebSocket推送的订阅与销毁用Options API写你会得到这样的结构export default { data() { return { keyword: , dateRange: [], status: , list: [], page: 1, pageSize: 20, total: 0, loading: false, selectedRows: [], socket: null, isExporting: false } }, computed: { filteredList() { /* ... */ }, isAdmin() { /* ... */ }, canExport() { /* ... */ } }, watch: { keyword() { this.page 1; this.fetchList() }, status() { this.page 1; this.fetchList() } }, methods: { fetchList() { /* 列表拉取 */ }, handleSearch() { /* 搜索 */ }, handleReset() { /* 重置 */ }, handleSelectionChange() { /* 多选 */ }, handleExport() { /* 导出 */ }, initSocket() { /* WebSocket */ }, destroySocket() { /* 销毁 */ }, // ... 还有十几个方法 }, mounted() { this.fetchList() this.initSocket() }, beforeUnmount() { this.destroySocket() } }看着整齐对吧但当你需要维护“搜索”这一个小功能时你得同时打开data、watch、methods、computed四个区域来回跳。搜索相关字段散落在二十几个字段中间搜索对应的handler和普通方法混在一起搜索引起的副作用藏在watch里。你的视线被迫在文件的各个角落来回漂移大脑需要手动“拼接”这些碎片才能真正理解一个功能的完整链路。组合式API恰恰是把这些碎片重新归位。你可以把搜索相关的所有字段、方法、副作用写在一块儿列表相关的写在一块儿多选相关的写在一块儿。代码库的阅读单位从“文件的选项块”变成了“功能块”。这看似只是代码摆放位置的调整实际上直接影响了你接手一个陌生组件时的认知成本。1.2 逻辑复用的天花板mixin的三宗罪如果说代码组织还只是“别扭”那逻辑复用就是Options API真正感觉无力的地方。Vue 2时代最常用的复用方案是mixin我参与过的项目里几乎都踩过它的坑。第一宗罪是命名冲突不可控。多个mixin同时定义了data里的同名字段或者methods里的同名方法最终生效的是谁取决于混入顺序而且Vue的合并策略是组件自身优先于mixin两个mixin之间则是后者覆盖前者。这个规则背起来容易但在多人协作、复用第三方mixin时根本防不住。我在一个项目里就亲眼见过一个mixin定义了init()方法组件自己也写了init()结果mixin的代码被静默覆盖页面某个初始化逻辑悄悄失效排查了整整一天。第二宗罪是来源不透明。看模板里的filteredList你根本不知道它来自哪个mixin、来自哪个全局混入、还是组件自己定义的。IDE跳转经常跳到一堆抽象层里一个看似简单的方法背后可能横跨五六个mixin。对于新接手的人来说这几乎是灾难。第三宗罪是隐式依赖。mixin之间可以互相依赖对方的字段和方法但这种依赖没有任何显式声明。A mixin用了B mixin里的this.userInfo一旦B被移除或者改名字A就悄悄坏掉。这种问题在编译期完全不报错只有运行到特定路径才暴露。组合式函数composable解决的正是这三个问题。它的核心思想很简单把一段完整的业务逻辑连同它的状态和方法一起封装成一个函数。调用方显式传入参数、显式接收返回值没有隐式共享没有命名空间污染一眼就能看出数据从哪里来、方法属于谁。1.3 类型推导Options API在TypeScript下的无力感2026年的项目基本默认TypeScript这一项几乎成了很多人转向组合式API的决定性原因。Options API在TypeScript下的核心问题是this。this依赖选项合并的隐式类型Vue官方需要通过复杂的defineComponent宏和类型推导才能让this上的数据和方法正确推断。可一旦遇到mixin、全局属性、自定义$bus之类的东西类型就变得非常吃力。写代码时满屏any、调方法时频频报错、IDE提示不可靠这些都是“你明明在写TS却享受不到类型保护”的典型症状。组合式API的思路完全不同。它在setup或script setup里直接使用普通函数和变量没有this的魔法。你写const keyword ref()它的类型就是Refstring你写const fetchList () {}它就是普通的函数类型。整个数据流和类型流是显式、确定的TypeScript可以精确推导IDE也能给出精准的提示。这不仅仅是“开发者体验更好”的层面更是工程层面的优势。类型安全意味着重构时能靠编译器兜底意味着API边界被强制表达清楚意味着大型团队协作时每个函数签名本身就是一份文档。2. 组合式API的设计内核把“功能”当作一等公民2.1 setup 到底解决了什么问题组合式API的核心入口是setup函数。在script setup这个语法糖普及之前你需要手动写setup()并返回所有需要暴露给模板的变量和方法略显繁琐。现在官方推荐的写法已经完全被script setup全面接管。但无论哪种写法setup的本质是一样的它让组件逻辑不必再被“选项”这个外壳约束。你可以这样理解——Options API像是一个分好类的文件柜data是一个抽屉、methods是一个抽屉、computed是一个抽屉你必须把东西拆开按类别放进去而Setup像一张空白的桌面你怎么摆放完全由你说了算更准确的说是由“功能边界”说了算。看一个最简单的对比script setup import { ref, computed, onMounted } from vue // 搜索功能字段 方法 副作用 都在一起 const keyword ref() const page ref(1) const search () { page.value 1 fetchList() } const reset () { keyword.value page.value 1 fetchList() } // 列表功能字段 方法 生命周期 也在一起 const list ref([]) const loading ref(false) const fetchList async () { loading.value true try { const res await getOrderList({ keyword: keyword.value, page: page.value }) list.value res.data } finally { loading.value false } } onMounted(() { fetchList() }) /script这段代码最大的变化不是少写了几个选项而是阅读路径变短了。你想看搜索功能往下扫一眼就能看到它完整的链路数据、行为、副作用都在一起。这跟人类理解业务的方式是一致的——我们本来就不是按“变量”“方法”“计算属性”来理解业务的我们按“登录功能”“购物车功能”“支付功能”来理解。2.2 用组合式函数组织复杂页面如果说setup只是把代码重新摆放了位置那组合式函数composable才是组合式API真正的高级形态。它把可复用的业务逻辑抽成一个带状态的函数命名上约定以use开头内部使用ref、reactive、computed、生命周期钩子等响应式API最终返回需要暴露的状态和方法。前面说的订单列表页用组合式函数可以抽成这样的结构// composables/useOrderList.js import { ref, onMounted, onBeforeUnmount } from vue export function useOrderList() { const list ref([]) const loading ref(false) const fetchList async () { // ... } onMounted(fetchList) return { list, loading, fetchList } }// composables/useOrderSearch.js import { ref, watch } from vue export function useOrderSearch(fetchList) { const keyword ref() const status ref() const page ref(1) watch([keyword, status], () { page.value 1 fetchList() }) return { keyword, status, page } }然后在页面组件里组合script setup import { useOrderList } from ./composables/useOrderList import { useOrderSearch } from ./composables/useOrderSearch import { useTableSelection } from ./composables/useTableSelection const { list, loading, fetchList } useOrderList() const { keyword, status, page } useOrderSearch(fetchList) const { selectedRows, handleSelectionChange } useTableSelection() /script这样抽的好处是立竿见影的第一页面组件只剩“组装”和“展示”的职责第二每个useXxx都可以单独测试第三如果另一个页面也需要列表搜索多选改改参数直接复用第四新成员看代码时只需要逐行读useXxx的实现不需要理解那个组件庞大的整体。我个人的经验是一旦你开始用组合式函数再回到Options API写页面会有种“手被绑住”的感觉——因为你会清晰地意识到很多逻辑原本根本不该堆在组件里。2.3 响应式API选择ref 还是 reactive 的取舍这是组合式API最容易被纠结的点也是面试高频题。ref和reactive都能创建响应式数据但正确选型可以省掉很多麻烦。先说我的结论业务代码里90%的情况优先用ref。原因有几个ref对类型的支持天然友好RefT可以直接推导ref在script setup模板中会自动解包写法上依然流畅reactive有一个很隐蔽的坑——解构后响应性丢失。// reactive 解构丢失响应性的反面教材 const state reactive({ keyword: , page: 1, total: 0 }) // 在另一个方法里解构 const { keyword, page } state keyword.value xxx // 这不会更新 state.keyword有人会用toRefs来解决解构问题但这等于给每个字段额外包了一层反而多了一些心智负担。而ref从一开始就没这个问题const keyword ref() const page ref(1) const total ref(0)当然reactive也不是一无是处。当你要维护一个结构固定、字段较多的对象比如表单模型时reactive能让代码更像“操作一个普通对象”const form reactive({ username: , password: , rememberMe: false, captcha: }) // 提交时直接收集 const submit () { api.login({ ...form }) }对于这种场景reactive表达力更强。我的建议是用一个reactive组织一组强相关的字段用多个ref表达独立的状态。不要在一个组件里上百个ref平铺也不要试图用一个巨大的reactive装下整个世界。按功能域拆分后每个useXxx内部的字段数量自然就控制住了。3. 从 Options API 迁移到组合式API的实操路线3.1 最小侵入迁移setup入口先跑通很多人想迁移但被“重构整个组件”这件事吓住了。其实没必要一上来就推倒重来。组合式API和Options API在同一个组件里是可以并存的。Vue 3允许你返回setup的响应式数据和方法同时继续使用data、methods、computed这些选项。两者通过this共享数据。所以最稳妥的迁移策略是在保留原有Options API结构的同时新写的逻辑一律用setup或组合式函数处理。比如老组件要加一个“批量导出”功能你可以直接新建一个useExport.js在组件里调用完全不碰原来的data和methods。这样既不会破坏现有逻辑又让新代码走上了正确路线。当组件里的新逻辑逐渐增多后你会自然产生“把旧逻辑也搬进去”的冲动。到那个阶段再分步迁移也不迟。3.2 按功能域抽取composables的具体手法抽取并不是简单地“把代码挪进函数”而是有手法可循的。根据我重构多个页面的经验核心步骤是这几步第一步画功能地图。别急着写码。打开老组件把页面包含的功能域列出来。比如购物车列表、优惠券选择、库存校验、金额计算、提交订单、倒计时提醒。每个功能域标注涉及的数据字段、方法、计算属性、watch、生命周期钩子。第二步以功能为单位搬运。先挑一个功能域把它涉及的所有内容整体搬到一个useXxx函数里。这一步的关键是暂不管这个功能域是否会被复用先让它“内聚”起来。哪怕只在一个组件里使用组合式函数也能显著提升可读性。第三步显式处理依赖关系。原Options API里功能之间经常通过this隐式互访抽成函数后必须显式传递。比如useOrderSearch需要触发fetchList那就作为参数传进去。这种“显式化”的过程本质上是在帮你理清代码的隐藏耦合。第四步整理返回值和类型。组合式函数的返回值要克制。只返回这个功能域对外暴露的状态和方法内部中间变量不要暴露。如果使用TypeScript给每个返回参数标注具体类型。一个典型的功能地图大概长这样功能域核心状态行为副作用来源搜索keyword, status, pagesearch, resetwatch触发fetchList列表list, loading, totalfetchListmounted拉取多选selectedRows, isAllSelectedhandleSelectionChange-导出exporting, exportStatushandleExport手动触发WebSocketsocket, latestMessageinitSocket, destroySocketmounted / beforeUnmount这张表就是你改造的施工图。3.3 逐步替换的路线图与优先级如果你负责的是一个关键业务系统不可能一次性把所有组件全部改造完。我建议按以下优先级推进新功能新页面直接用组合式API。这是零成本的一步从今天就可以开始。高复用逻辑优先抽取。比如权限判断、分页、搜索、表单校验、WebSocket连接这些跨页面都在用的逻辑抽成usePermission、usePagination、useFormValidation、useWebSocket后收益最大。复杂度高的老组件逐步迁移。从最复杂的那个页面开始先抽功能地图然后一个功能域一个功能域地搬。简单组件保持不变。一个只有三五个变量、两个方法的展示型组件用Options API完全没问题没必要为了“新”而“新”。另外提一个容易忽略的点如果你们还在用Vue 2.7其实不必等到Vue 3就能用上组合式API。Vue 2.7官方正式支持组合式API组件库层面也有很多兼容方案。这意味着即便老项目暂时不能升级Vue 3你依然可以在现有代码里逐步引入script setup风格和组合式函数提前为将来升级铺路。4. 我的真实项目复盘一个复杂页面的重构前后对比4.1 重构背景和页面功能清单为了说清楚我拿我们团队前阵子重构的一个“对账单管理”页面举例。这个页面在后台管理系统里属于中型偏复杂的页面功能清单如下搜索条件订单号、商户名称、结算状态、时间范围合计6个查询参数表格列表服务端分页默认按时间倒序支持按金额排序多选支持跨页多选顶部显示已选数量批量导出选中数据导出Excel带导出进度提示详情抽屉点击某行弹出详情详情里包含若干子表WebSocket推送当有新的结算完成时列表头显示“有更新”角标点击后刷新列表重构前这个组件写在单文件里template部分800行script部分650行style部分200行。data里有34个字段methods里35个方法computed里13个计算属性watch里6个监听器。代码的复杂程度已经明显影响排期——每次改动这个页面前后端联调时间都得额外加半天。4.2 重构前后的代码组织对比我们花了两个迭代的时间把这个页面按功能域拆分成了5个组合式函数useSearchForm6个查询参数 重置 触发搜索useTable列表数据 loading 分页 排序useSelection跨页多选 已选计数useExport导出状态 导出进度 触发导出useRealTimePushWebSocket连接 新消息角标 销毁每个useXxx文件大约80到150行页面主组件的script从650行降到了180行左右。这180行里绝大部分是“接线”代码调用组合式函数把数据和事件绑定到模板。对比一下重构前后的差异维度重构前Options API重构后Composition API主组件script行数650行约180行功能间耦合通过this隐式互访显式传参新成员理解成本需要通读全组件按composable逐个阅读可测试性需要挂载组件可直接测试组合式函数逻辑复用mixin冲突风险高组合式函数无冲突峰值体验来自一次需求变更产品要求把“跨页多选”从对账单页复制到另一个“退款记录”页面。按以前的做法得把那一堆选中逻辑连同几十行状态一起复制过去然后把字段名全部改一遍。这次我们只做了一件事在退款记录页引入useSelection传入不同的标识字段完事。4.3 踩过的坑和性能实测迁移不是没有代价的这里记录几个我们踩过的坑。坑一watch监听reactive对象时旧值不是深拷贝。在Options API里watch一个对象的习惯是直接监听整个对象。搬到组合式API后我们用watch(() state.filter, (newVal, oldVal) ...)结果发现oldVal和newVal指向同一个引用对比失效。原因在于组合式API的watch默认不会深拷贝旧值。解决方案是手动浅拷贝watch(() ({ ...state.filter }), ...)。这个细节官方文档有提但实际写的时候很容易忽略。坑二ref在reactive对象里会被自动解包。有一次我们把多个ref放进一个reactive对象统一管理结果发现模板里访问时不需要.value但脚本里访问又需要.value来回切换非常容易出错。后来我们统一了规范组合式函数之间传递状态时优先传递ref本身而不是把ref塞进reactive。坑三定时器和WebSocket的清理时机。组合式函数里的onMounted注册的定时器如果不在onBeforeUnmount里清理组件销毁后依然会运行。我们曾有一个页面路由切换后WebSocket还在后台推送控制台刷屏。排查后发现是组合式函数里只写了onMounted(initSocket)忘了销毁。现在团队规范明确规定在组合式函数里注册的任何定时器、事件监听、网络连接必须在同函数内清理。性能方面重构前后这个页面的首屏渲染时间没有明显变化——这也是正常的组合式API本身不带来性能上的突破性优势。它带来的收益是开发和维护效率而不是运行时性能。如果有人告诉你“组合式API更快”那是在误导你。5. 组合式API的边界与理性建议2026年视角5.1 什么时候可以继续用Options API这可能是很多人不敢问的问题难道所有地方都必须用组合式API吗我的答案是不至于。有几种情况用Options API完全没有问题极简单的展示型组件。一个组件里只有两三个props、一个emit、一段简单的展示逻辑。用Options API能写得很紧凑用组合式API反而显得“杀鸡用牛刀”。团队里有Vue 2历史包袱的老项目。如果项目还没升级Vue 3且短期内没有升级计划在Vue 2里强行写一堆组合式API只会增加额外成本。这时候更现实的路线是用Vue 2.7渐进迁移。配Options API写起来更直观的场景。比如一个数据字典类型的单项选择组件数据量小、交互简单datamethodscomputed三件套足够清楚。这不是“和稀泥”而是实事求是。组合式API是更强大的工具但工具的强弱不代表每个场景都必须用它。关键是你要有判断力这个组件会变复杂吗这段逻辑会复用到别处吗团队能接受新的心智模型吗5.2 组合式API搭配TypeScript和Pinia的完整姿势2026年的Vue项目标准的三件套已经比较清晰组合式API TypeScript Pinia。Pinia本身就是组合式风格的状态管理库和组合式API配合起来非常顺畅。这里有个实操建议Pinia的store也建议用setup语法来写。Pinia支持defineStore传入一个类似setup的函数也能传入Options风格的配置。我推荐setup语法因为这个模式下store内部的状态、getter、action完全是组合式API的写法可以在store里调用其他store也可以复用业务里的组合式函数灵活性更强。import { defineStore } from pinia import { ref, computed } from vue import { useUserStore } from ./user export const useOrderStore defineStore(order, () { const orders refOrderItem[]([]) const loading ref(false) const userStore useUserStore() const totalAmount computed(() orders.value.reduce((sum, item) sum item.amount, 0) ) async function fetchOrders() { loading.value true try { const res await api.getOrders({ userId: userStore.userId }) orders.value res.data } finally { loading.value false } } return { orders, loading, totalAmount, fetchOrders } })这样写的好处是store内部的逻辑不再被state、getters、actions三个区块割裂业务内聚原则贯穿到了状态管理层。TypeScript方面我特别推荐给组合式函数写清晰的入参和出参类型。不要为了省事把所有函数都写成(params: any) any。组合式API最大的优势之一就是类型推导你不利用起来等于亲手扔掉了这个工具最大的价值。5.3 团队落地组合式API的规范建议如果你们团队决定全面转向组合式API建议提前定好规范避免每个人风格不同导致代码混乱。以下几点是经过多个项目验证的规范经验组合式函数统一放入composables目录按模块或领域分子目录命名统一use开头。组合式函数的返回值尽量以对象形式返回除非只有单个返回值才直接用ref。这样调用方可以自由解构而解构ref对象是安全的。组合式函数的职责边界要清晰。一个useXxx最好只负责一个功能域。如果一个函数超过200行考虑拆成更小的函数。副作用必须自带清理逻辑。定时器、事件监听、WebSocket、IntersectionObserver等都在函数内部注册时一并注册清理逻辑组件卸载时自动执行。UI状态与业务状态分离。像isLoading、isModalVisible这类纯UI状态可以保留在组件内部不需要都抽出去而像订单列表、用户信息、权限集合这类业务状态才值得放进组合式函数或Pinia。代码评审时重点看响应式边界。比如是否有人把reactive对象当作普通对象解构使用是否有人在组合式函数外修改了函数内部创建的ref这些都是容易产生隐蔽bug的地方。这些规范不是僵硬的规定而是为了减少团队成员之间的认知差异。组合式API给了开发者极大的自由但这个自由也需要边界才能形成稳定生产力。最后再说一点实际的体会。我见过有人把组合式API当成“新玩具”不管什么组件都硬拆成七八个composable结果代码比原来还难读。组合式API的核心不是“把文件拆小”而是“以业务功能为单位组织代码”。当你发现自己写代码时不再需要记住“这个字段在data里、那个方法在methods里”而是能顺着一个功能的完整链路一路读下去那才是真正掌握了它的正确姿势。如果现在你手里有个写着费劲的老组件给它画一张功能地图挑一个最独立的功能域抽成useXxx跑通之后你就能直观体会到差别。别等整个项目统一升级了再动手从下一个需求、下一个页面开始用组合式API写出来上手这件事真的没你想象中那么难。