Vue 3.0 Composition API是什么？新手该怎么上手？

作者：Terry2025.05.16来源：Web前端之家浏览：59评论:0

关键词：Composition API

很多刚接触Vue 3的开发者都会问：“Composition API到底是什么？和以前的Options API有什么区别？新手该从哪里开始学？” 作为Vue 3最核心的新特性之一，Composition API的出现不仅改变了组件的写法，更重新定义了逻辑复用和代码组织的方式，今天我们就用问答的形式,把这些问题一次性说清楚。

Composition API到底解决了什么问题？

要理解Composition API，得先回顾Vue 2的Options API（选项式API），过去写Vue组件时，我们习惯把数据放在data里，方法放在methods，计算属性放在computed，生命周期钩子单独写，这种“按选项分类”的方式在小项目里没问题，但一旦组件变复杂，问题就暴露了：比如一个组件同时需要处理表单验证、数据请求和用户权限，相关的代码会被拆分成data里的变量、methods里的函数、watch里的监听，逻辑被“打散”在不同选项里，维护起来像翻字典——找一个功能的代码要跳好几个地方。

Composition API的核心就是“按逻辑功能分类”，它允许开发者把相关的逻辑（获取用户数据”和“处理加载状态”）封装成一个函数，需要时直接引入，代码结构从“纵向分块”变成“横向组合”，举个简单例子：一个组件需要同时处理倒计时和表单校验，用Options API可能要在data里写两个变量，methods里写两个函数；用Composition API则可以把倒计时逻辑写成useCountdown函数，表单校验写成useFormValidation函数，在setup里直接调用，代码更紧凑,逻辑也更清晰。

新手该如何快速上手Composition API？

新手入门Composition API，关键要抓住三个核心：setup函数、响应式系统、逻辑抽离。

第一步：理解setup函数
setup是Composition API的入口，组件创建时会先执行setup，它的返回值会暴露给模板或其他选项（比如render函数），需要注意的是，setup里不能使用this（因为执行时组件实例还没创建）,数据和方法需要显式返回才能在模板中使用。

// 错误写法：this在setup中不可用
setup() {
  console.log(this) // undefined
}
// 正确写法：返回对象供模板使用
setup() {
  const count = ref(0)
  const add = () => count.value++
  return { count, add }
}

第二步：掌握响应式工具
Vue 3提供了ref和reactive两个核心响应式工具，ref用于基本类型（数字、字符串）和对象的响应式处理，访问时需要.value；reactive用于对象（数组、对象）的深层响应式,直接访问属性即可。

// ref处理基本类型
const name = ref('张三')
console.log(name.value) // 输出：张三
// reactive处理对象
const user = reactive({ age: 20 })
console.log(user.age) // 输出：20（无需.value）

新手容易踩的坑是：用reactive包裹基本类型（比如reactive(123)），这时候数据不会响应式更新,正确做法是用ref。

第三步：学会抽离逻辑到组合函数
Composition API的灵魂是“逻辑复用”，通过组合函数（官方叫Composables）可以把重复的逻辑封装成独立函数，比如项目中多个组件需要“获取用户位置”的功能,就可以写一个useGeolocation函数：

// composables/useGeolocation.js
export function useGeolocation() {
  const position = ref({ latitude: 0, longitude: 0 })
  const error = ref(null)
  const getPosition = () => {
    navigator.geolocation.getCurrentPosition(
      (pos) => {
        position.value = {
          latitude: pos.coords.latitude,
          longitude: pos.coords.longitude
        }
      },
      (err) => { error.value = err }
    )
  }
  return { position, error, getPosition }
}

在组件里引入后，直接调用就能复用逻辑，比Vue 2的mixins更灵活（mixins会有变量命名冲突的问题，而组合函数返回的变量名可以自定义）。

和Options API相比，Composition API有哪些明显优势？

很多人会问：“既然Options API能用，为什么还要学Composition API？” 答案藏在三个实际开发场景里：

复杂组件的代码可读性
假设有一个用户信息组件，需要处理“用户数据加载”“表单编辑”“权限校验”三个逻辑，用Options API时，data里会有userInfo、formData、isAdmin三个变量，methods里有fetchUser、saveForm、checkPermission三个函数，代码分散在不同选项中，用Composition API则可以把这三个逻辑分别写成useUserFetch、useFormEdit、usePermissionCheck三个函数，在setup里引入后，代码像拼积木一样清晰,找某个功能的代码只需要看对应的组合函数。

逻辑复用的灵活性
Vue 2的mixins虽然能复用逻辑，但存在两个问题：一是多个mixins有同名变量时会冲突，二是无法知道mixins里的变量来自哪里（“幽灵变量”问题），而组合函数返回的变量可以自由命名（比如可以把useCountdown返回的count重命名为timerCount），且每个逻辑的来源明确,调试时更方便。

TypeScript支持更友好
Vue 3对TS的支持大幅提升，而Composition API的函数式写法天然和TS契合，比如组合函数可以明确标注返回值的类型，组件中的变量类型推导也更准确,减少了手动声明类型的工作量。

使用Composition API时常见的误区有哪些？

新手在学习过程中容易犯以下错误,需要特别注意：

误区1：过度拆分逻辑
有些开发者为了“复用”而拆分，把简单的逻辑（比如一个按钮的点击计数）也写成组合函数，反而增加了代码复杂度，建议：只有重复使用的逻辑（比如多个组件都需要的“图片懒加载”）才封装成组合函数,单个组件内的逻辑保持内联即可。

误区2：忽略响应式规则
前面提到ref需要通过.value访问，但有些新手会直接修改ref的原始值（比如count = 5而不是count.value = 5），导致页面不更新，reactive对象的属性如果是基本类型（比如user.age = 25），修改时是响应式的，但如果直接替换整个对象（user = { age: 25 }）,需要用ref包裹才能保持响应式。

误区3：在setup外使用生命周期钩子
Vue 3的生命周期钩子（如onMounted）必须在setup或组合函数内部同步调用,不能在异步函数或条件判断里延迟调用。

// 错误写法：在setTimeout里调用
setup() {
  setTimeout(() => {
    onMounted(() => {}) // 无效！
  }, 0)
}
// 正确写法：同步调用
setup() {
  onMounted(() => {
    setTimeout(() => { /* 业务逻辑 */ }, 0)
  })
}