Vue3 的 Composition API 和 Options API 到底该怎么选？有没有权威的判断标准？

最近翻前端交流群，三天两头能看到刚转Vue3或者做中大型项目重构的朋友在纠结API选择：有人说Composition API是官方亲儿子，全换掉才是紧跟主流；有人习惯了Options API按功能分模块的逻辑，觉得改了反而不顺手；还有人试着混用，但越混越乱，组件维护成本直线上升，其实我自己刚用Vue3的时候也踩过这个坑——公司一个老电商组件库从Options API全转Composition API，结果刚毕业的实习生完全看不懂逻辑，只能边查文档边问，项目迭代慢了一周多，后来翻了很多实战经验，又结合官方的底层设计思路，慢慢摸出了一套比较稳妥的判断方法,今天就分享给大家。

先搞懂：两种API的本质区别是什么？

很多人纠结选不选，根本原因是没搞懂这俩API到底哪里不一样，只是听别人说“Composition API更灵活”“Options API更易上手”，其实从设计初衷看，它们根本不是“替代关系”，而是“互补关系”——官方从来没说过要放弃Options API,反而一直保证向后兼容。

先说说大家更熟悉的Options API，它的核心逻辑是“按代码性质分类”：数据放在data里，方法放在methods里，生命周期钩子按created/mounted/unmounted顺序排，计算属性computed、侦听器watch单独放一块，这种写法的好处是新手一看就知道“哪里放变量”“哪里写交互”，对Vue2过来的开发者太友好了，代码结构像搭积木，每个模块的职责边界清晰得像画了线，但缺点也很明显：如果组件逻辑超过一定复杂度（比如电商的商品筛选组件，既要处理价格区间、销量排序、标签筛选，还要和接口联动、做本地缓存），同一个功能的代码会被拆得七零八落——处理标签筛选的变量在data，重置方法在methods，初始化标签的逻辑在mounted，监听标签变化的逻辑在watch，你想看懂整个筛选流程，得上下滚动N次代码，非常割裂；而且代码复用只能靠mixins，但mixins的问题大家都懂：变量来源不明、容易冲突、多mixins混用时调试困难。

再说说后来居上的Composition API，它的核心逻辑是“按功能逻辑分类”：你可以把处理同一个功能的所有代码（变量、方法、生命周期、计算属性、侦听器）放在一起，甚至可以封装成一个自定义Hook，抽出去复用，比如刚才说的商品筛选组件，你可以封装一个useGoodsFilter的Hook，里面放priceRange变量、updatePriceRange方法、watch标签变化的逻辑、mounted初始化本地缓存的逻辑，主组件只需要引入Hook，拿到需要的变量和方法就行，整个组件的逻辑像串珠子，一眼就能看到哪部分是处理什么的；而且代码复用靠Hook，比mixins安全太多——变量可以命名空间化，不用怕冲突，Hook的逻辑也可以单独测试,不用依附于组件。

别听传言：官方有没有给出明确的API选择建议？

很多人觉得“官方推Composition API，所以新项目全用Composition API就行”，其实官方根本没给“一刀切”的建议，反而给出了几个核心判断维度，我整理了一下,结合实战场景补充了一些细节：

第一个维度是团队成员的技术背景，如果你的团队大部分都是刚接触Vue的新手，或者主要是Vue2过来的、对函数式编程不太熟悉的开发者，那先别急着全转Composition API——新手学Options API的门槛更低，能快速上手做项目；Vue2过来的开发者需要时间适应Composition API的响应式原理（ref/reactive/toRefs这些东西）和逻辑组织方式，硬推反而会降低开发效率，但如果你的团队有经验丰富的Vue3开发者，或者准备用TypeScript开发（Composition API对TS的支持比Options API好太多），那直接用Composition API是更好的选择。

第二个维度是组件的逻辑复杂度，这个是官方最看重的判断标准，也是我自己实战中用得最多的，怎么判断组件的逻辑复杂度？官方给了一个简单的参考：如果组件不需要复用逻辑，代码行数在200行以内，逻辑只有“展示数据+简单交互（比如点击按钮提交表单）”，那用Options API完全没问题——这种简单组件用Options API写，结构清晰，维护起来也方便；但如果组件逻辑超过200行，需要复用多个功能逻辑，或者逻辑涉及到多个生命周期钩子联动、多层侦听器嵌套，那一定要用Composition API——不然你会发现，代码拆得太散，改一个功能要改好几个地方,还容易漏改。

第三个维度是项目的类型和长期规划，如果你的项目是一个短期项目（比如活动页、落地页），或者是一个功能简单的内部工具，那用什么API都行，怎么快怎么来；但如果你的项目是一个长期维护的中大型项目（比如电商平台、企业管理后台），那建议用Composition API——因为中大型项目的组件逻辑会越来越复杂，代码复用的需求也会越来越多，Composition API的可维护性和可扩展性会比Options API好很多，比如我们公司的老电商项目重构的时候，简单的Banner组件、按钮组件还是用Options API，但是商品筛选组件、购物车组件、订单管理组件这些复杂组件，全转成了Composition API，还封装了20多个自定义Hook，后来迭代新功能的时候，直接复用Hook就行，开发效率提高了30%左右。

避坑指南：怎么正确混用两种API？

很多人说“官方说可以混用，但我越混越乱”，其实混用是有技巧的，不能随便乱混，官方给的混用原则是：尽量不要在同一个组件里同时用Options API和Composition API的响应式数据——比如不要在data里定义一个变量，然后在setup里又去修改它，不然会导致响应式逻辑混乱,调试起来非常麻烦。

那怎么正确混用？我自己总结了两种常见的场景：

第一种场景是老项目渐进式重构，比如你有一个Vue2转Vue3的老项目，有100个组件，不可能一下子全转成Composition API——这时候你可以先把复杂的组件转成Composition API，封装成自定义Hook，简单的组件还是用Options API；或者在同一个Options API组件里，用setup函数来封装一部分复杂的逻辑，然后通过return把需要的变量和方法暴露给Options API的其他部分，

// 老项目渐进式重构的例子
import { ref, onMounted } from 'vue'
export default {
  data() {
    return {
      // 保留简单的响应式数据
      isShowBanner: true
    }
  },
  setup() {
    // 封装复杂的商品筛选逻辑
    const priceRange = ref([0, 1000])
    const updatePriceRange = (val) => {
      priceRange.value = val
    }
    onMounted(() => {
      // 初始化本地缓存的价格区间
      const cachedPriceRange = localStorage.getItem('priceRange')
      if (cachedPriceRange) {
        priceRange.value = JSON.parse(cachedPriceRange)
      }
    })
    // 暴露给Options API的其他部分
    return {
      priceRange,
      updatePriceRange
    }
  },
  methods: {
    // 保留简单的交互方法
    toggleBanner() {
      this.isShowBanner = !this.isShowBanner
    }
  }
}

这种写法既能渐进式重构，又不会导致逻辑混乱,老开发者和新开发者都能接受。

第二种场景是组件中有少量Options API专属的功能，什么是Options API专属的功能？比如name、inheritAttrs、components、directives这些配置项，虽然Composition API也有对应的写法（比如defineOptions、defineComponent），但有时候用Options API的写法更简洁；还有比如provide/inject，虽然Composition API也有，但如果只是简单地在根组件provide，在子组件inject，用Options API的写法更顺手。

实战案例：不同场景下的API选择

说了这么多理论，不如给大家举几个实战案例,更直观：

第一个案例是电商的商品详情页的分享按钮组件，这个组件的逻辑很简单：展示一个分享图标，点击图标弹出分享弹窗，弹窗里有微信好友、朋友圈、微博几个分享渠道，点击渠道调用对应的SDK，逻辑不超过100行，不需要复用，这时候用Options API完全没问题——代码结构清晰,新手也能看懂。

第二个案例是电商的商品列表页的商品筛选组件，这个组件的逻辑很复杂：要处理价格区间、销量排序、上新时间排序、商品标签筛选、品牌筛选，还要和后端接口联动、做分页、做本地缓存，还要支持移动端和PC端的适配，代码行数超过500行，复用的需求也很多（比如订单管理页也要用到类似的时间筛选、状态筛选逻辑），这时候一定要用Composition API——封装成useGoodsFilter、usePagination、useLocalCache几个自定义Hook，主组件只需要引入Hook，拿到需要的变量和方法就行，逻辑清晰，维护方便,还能复用。

第三个案例是企业管理后台的权限控制Hook，这个Hook不是组件，是一个需要在很多组件里复用的逻辑：要判断用户有没有某个权限，没有的话隐藏对应的按钮或者路由，还要监听用户权限的变化，实时更新界面，这时候只能用Composition API——因为Hook是基于Composition API的setup函数的，Options API没法封装成独立的、可复用的Hook。

适合自己的才是最好的

其实不管是Composition API还是Options API，都没有绝对的好坏之分，只有适合不适合之分，官方从来没说过要放弃Options API，反而一直保证向后兼容，就是为了让不同的团队、不同的场景都能找到适合自己的API。

所以大家不用纠结“全转Composition API才是紧跟主流”，也不用固执“只用Options API才是王道”，根据自己的团队技术背景、组件逻辑复杂度、项目长期规划来选择就行——简单组件用Options API，复杂组件用Composition API，老项目渐进式重构，新项目如果有条件直接用Composition API（尤其是用TypeScript的话）,这样才能最大化地提高开发效率和代码可维护性。

如果你还是不知道怎么选，可以试试这个简单的测试方法：先写一个100行以内的简单组件，用两种API各写一遍，看哪个写得更快、更顺手；再写一个300行以上的复杂组件，用两种API各写一遍，看哪个逻辑更清晰、维护更方便；最后再结合自己的团队情况，决定用哪种API为主,哪种API为辅。