1. 从“选项”到“组合”：Vue 3 的范式演进

如果你是从 Vue 2 时代一路走来的开发者，第一次打开 Vue 3 的官方文档，可能会有点恍惚。那个熟悉的、以data、methods、computed等选项块组织代码的“选项式 API”依然存在，但旁边却多了一个看起来更“函数式”的“组合式 API”。这不仅仅是多了一种写法那么简单，它代表着 Vue 在应对现代前端应用日益增长的复杂性时，所做出的一次根本性的设计思想转变。简单来说，选项式像是给你一套固定格式的表格让你填写，清晰但受限；而组合式则是给了你一盒乐高积木，让你可以自由地拼装出任何你想要的逻辑结构。理解这两种范式，不仅是学习 Vue 3 的语法，更是理解如何构建更健壮、更易维护的前端应用的关键。

2. 选项式 API：经典的“配置表”哲学

2.1 核心概念与结构解析

选项式 API 是 Vue 2 的遗产，也是大多数 Vue 开发者入门时接触的第一种模式。它的核心思想是将组件的不同关注点，分别放入对应的“选项”对象属性中。整个组件就像一份结构化的配置表。

一个典型的选项式组件看起来是这样的：

<template> <div> <p>{{ count }}</p> <p>{{ doubledCount }}</p> <button @click="increment">增加</button> <button @click="decrement">减少</button> </div> </template> <script> export default { // 数据选项 data() { return { count: 0, message: 'Hello Vue!' }; }, // 计算属性选项 computed: { doubledCount() { return this.count * 2; } }, // 方法选项 methods: { increment() { this.count++; }, decrement() { this.count--; } }, // 生命周期钩子选项 mounted() { console.log('组件已挂载，当前count:', this.count); }, watch: { // 侦听器选项 count(newVal, oldVal) { console.log(`count 从 ${oldVal} 变更为 ${newVal}`); } } }; </script>

这种写法的最大优点是直观和低门槛。对于新手或者逻辑简单的组件，你可以一目了然地找到数据在哪（data）、方法在哪（methods）、计算属性在哪（computed）。所有东西都分门别类地放在固定的“抽屉”里，学习曲线平缓。此外，选项式 API 对this的依赖虽然有时会带来困惑，但在其上下文中，this始终指向当前组件实例，可以方便地访问到data、props、methods等所有属性。

2.2 优势与适用场景

选项式 API 并非过时，它在以下场景中依然有其独特的价值：

1. 原型开发与简单应用：当你需要快速搭建一个功能简单、逻辑清晰的页面或小组件时，选项式的“填空”模式效率很高。
2. 低复杂度项目或初学者：对于小型项目或刚入门的前端开发者，选项式提供了清晰的结构和较少的抽象概念，更容易上手和理解“Vue 是如何工作的”。
3. 迁移和维护 Vue 2 项目：如果你的团队有大量 Vue 2 遗产代码，继续使用选项式可以保持代码风格的一致性和可维护性，降低迁移成本。Vue 3 完全兼容选项式 API，这意味着你可以在 Vue 3 项目中无缝使用现有的 Vue 2 风格组件。

注意：在 Vue 3 中使用选项式 API 时，你仍然可以享受 Composition API 带来的诸多底层优化和新特性，例如更快的渲染速度、更小的包体积、更好的 TypeScript 集成等。你并不是在用一个“旧版本”的功能。

2.3 面临的挑战与局限性

然而，随着组件逻辑复杂度的提升，选项式 API 的缺点会逐渐暴露：

1. 逻辑关注点分离：这是最核心的问题。假设一个组件需要处理“用户搜索”这个功能，相关的逻辑（数据、方法、计算属性、侦听器、生命周期）会被迫分散在data、methods、computed、watch、mounted等多个选项中。当你要阅读或修改这个搜索功能时，需要在文件里上下反复跳转。这种基于“选项类型”的代码组织方式，割裂了基于“业务逻辑”的代码内聚性。
2. 逻辑复用困难：在 Vue 2 时代，跨组件复用逻辑主要依靠 mixins。但 mixins 存在命名冲突、数据来源不清晰、多个 mixin 交互时复杂度激增等问题。虽然选项式 API 也可以使用 Composables（组合式函数），但远不如在组合式 API 中那么自然和强大。
3. TypeScript 集成：选项式 API 对 TypeScript 的类型推导支持不如组合式 API 完善和优雅，尤其是在使用this上下文时，类型推断有时需要额外的类型声明。

3. 组合式 API：灵活的“乐高积木”哲学

3.1 核心概念：setup()函数与响应式 API

组合式 API 的设计初衷就是为了解决选项式 API 在复杂场景下的痛点。它的核心是一个新的组件选项：setup()函数。setup()在组件创建之前执行，它是组合式 API 的“舞台”。

在setup()中，你不再需要将代码分割到不同的选项里，而是可以像编写普通 JavaScript 函数一样，自由地组织你的逻辑。Vue 3 提供了一系列的响应式 API（如ref,reactive,computed,watch）来帮助你创建和管理响应式状态与副作用。

让我们用组合式 API 重写上面的计数器例子：

<template> <!-- 模板部分和选项式完全一样 --> <div> <p>{{ count }}</p> <p>{{ doubledCount }}</p> <button @click="increment">增加</button> <button @click="decrement">减少</button> </div> </template> <script> import { ref, computed, onMounted, watch } from 'vue'; export default { setup() { // 1. 定义响应式状态（替代 data） const count = ref(0); const message = ref('Hello Vue!'); // 2. 定义计算属性（替代 computed） const doubledCount = computed(() => count.value * 2); // 3. 定义方法（替代 methods） function increment() { count.value++; } function decrement() { count.value--; } // 4. 生命周期钩子（替代 mounted, created 等） onMounted(() => { console.log('组件已挂载，当前count:', count.value); }); // 5. 侦听器（替代 watch） watch(count, (newVal, oldVal) => { console.log(`count 从 ${oldVal} 变更为 ${newVal}`); }); // 6. 返回所有需要在模板中使用的变量和方法 return { count, message, doubledCount, increment, decrement }; } }; </script>

初看之下，代码似乎变长了，但请注意其结构：所有与计数器相关的逻辑（状态、计算、方法、副作用）都紧密地聚集在setup()函数顶部的一小块区域里。要理解或修改计数器功能，你只需要阅读这一小段代码即可，无需在文件中跳跃。

3.2<script setup>：语法糖带来的极致体验

上述setup()函数的写法虽然解决了逻辑聚合问题，但仍有模板（需要返回一个对象）和类型标注上的些许不便。为此，Vue 3.2 引入了<script setup>语法糖，它提供了更简洁、更符合直觉的写法。

<template> <div> <p>{{ count }}</p> <p>{{ doubledCount }}</p> <button @click="increment">增加</button> <button @click="decrement">减少</button> </div> </template> <script setup> // 导入的 API 和组件自动可用，无需再通过 `components` 选项注册 import { ref, computed, onMounted, watch } from 'vue'; // 声明变量和方法，它们在模板中自动可用 const count = ref(0); const message = ref('Hello Vue!'); const doubledCount = computed(() => count.value * 2); function increment() { count.value++; } function decrement() { count.value--; } onMounted(() => { console.log('组件已挂载'); }); watch(count, (newVal, oldVal) => { console.log(`count 变更: ${oldVal} -> ${newVal}`); }); </script>

<script setup>是编译时语法糖，它背后的原理仍然是setup()函数，但省去了显式的setup()定义和return语句。在<script setup>中顶层的绑定（变量、函数、import导入的组件）都会自动暴露给模板。这带来了几个巨大优势：

1. 更少的样板代码：代码量显著减少，更加简洁。
2. 更好的 TypeScript 支持：类型推断更加完美，几乎不需要手动标注类型。
3. 更好的运行时性能：因为所有内容都在编译时确定，所以有更好的优化空间。

实操心得：对于所有新的 Vue 3 项目，我强烈推荐直接使用<script setup>语法。它现在是 Vue 单文件组件（SFC）的官方推荐写法。唯一的例外是当你需要与尚未升级的选项式组件库或特定工具深度集成时，可能需要回退到标准的<script>标签。

3.3 核心响应式 API 深度解析

理解组合式 API，本质上是理解其提供的一系列响应式工具函数。这里深入解析几个最核心的：

refvsreactive这是初学者最容易混淆的一对。ref用于定义单个响应式数据，它返回一个具有.value属性的响应式对象。在模板和reactive对象中，Vue 会自动“解包”.value。

const count = ref(0); // 定义 console.log(count.value); // 访问 -> 0 count.value++; // 修改

reactive用于定义一个响应式对象，它返回一个对象的响应式代理。

const state = reactive({ count: 0, message: 'hello' }); console.log(state.count); // 访问 -> 0 state.count++; // 修改

如何选择？

• 优先使用ref：这是社区更推崇的做法。因为ref对原始值和对象都适用，且在整个组合式函数中传递时始终保持响应性（reactive在解构或传入函数后可能丢失响应性）。ref的.value虽然多写几个字符，但明确了“这是一个响应式引用”，意图更清晰。
• 使用reactive的场景：当你明确知道要定义的是一个紧密关联的、不会被解构的本地状态对象时。例如，一个表单的所有字段。

computed计算属性，用于定义依赖其他响应式状态的派生状态。它返回一个只读的ref对象。

const fullName = computed(() => `${firstName.value} ${lastName.value}`);

watch与watchEffect用于执行副作用（如数据变化时发起请求、操作DOM等）。

• watch：需要明确指定侦听的数据源和回调函数。更精确，能访问变化前后的值。

  watch(count, (newVal, oldVal) => { /* ... */ }); watch(() => state.someNested.prop, (newVal) => { /* ... */ }); // 侦听深层属性

• watchEffect：立即执行传入的函数，并自动追踪其依赖的响应式状态。依赖变化时，重新执行。更简洁，适用于依赖多个状态且不需要旧值的场景。

  watchEffect(() => { console.log(`count is: ${count.value}, message is: ${message.value}`); });

注意事项：watch和watchEffect在setup()或<script setup>中会自动绑定到当前组件的生命周期，在组件卸载时自动停止。但在异步回调中创建的侦听器需要手动清理，以避免内存泄漏。

4. 逻辑复用的革命：组合式函数

这是组合式 API 最强大的特性。你可以将可复用的逻辑提取为一个“组合式函数”。它就是一个普通的 JavaScript 函数，内部使用了 Vue 的响应式 API。

例如，我们将“鼠标位置跟踪”逻辑提取出来：

// useMouse.js import { ref, onMounted, onUnmounted } from 'vue'; export function useMouse() { const x = ref(0); const y = ref(0); function update(event) { x.value = event.pageX; y.value = event.pageY; } onMounted(() => window.addEventListener('mousemove', update)); onUnmounted(() => window.removeEventListener('mousemove', update)); // 返回响应式状态和方法 return { x, y }; }

然后在任何组件中像使用库函数一样使用它：

<script setup> import { useMouse } from './useMouse.js'; const { x, y } = useMouse(); </script> <template> 鼠标位置：{{ x }}, {{ y }} </template>

对比选项式的 Mixins：

1. 清晰的数据来源：组合式函数返回什么，组件就用什么，一目了然。Mixins 的数据和方法是“注入”到组件中的，来源不明。
2. 无命名冲突：组合式函数可以任意命名返回值，Mixins 的属性名冲突需要额外处理。
3. 灵活的传参：组合式函数可以接受参数，使其行为可定制。Mixins 很难做到这一点。
4. 更好的 TypeScript 支持：组合式函数能提供完整的类型推断。

社区已经基于此模式产生了大量优秀的工具库，如 VueUse ，提供了上百个开箱即用的组合式函数，极大地提升了开发效率。

5. 工程实践：如何在实际项目中应用与选型

5.1 新项目技术选型建议

对于全新的 Vue 3 项目，我的建议非常明确：全面拥抱组合式 API 和<script setup>语法。

技术栈推荐：

• 构建工具：Vite。其极速的热更新和构建体验与 Vue 3 是绝配。使用npm create vue@latest命令可以快速搭建一个集成了最新最佳实践的项目。
• 状态管理：对于中小型应用，优先考虑使用组合式函数（如useUserStore,useCartStore）来管理全局状态。对于大型复杂应用，Pinia 是官方推荐的状态管理库，它本身就是基于组合式 API 设计的，体验远优于 Vuex。
• 路由：Vue Router 4，完美支持组合式 API，提供了useRouter,useRoute等组合式函数。
• UI 框架：选择积极支持 Vue 3 和组合式 API 的组件库，如 Element Plus、Ant Design Vue、Naive UI 等。注意查看其文档是否提供了组合式 API 的使用示例。

5.2 从选项式到组合式的渐进迁移策略

对于已有 Vue 2（选项式）项目，不建议一次性重写所有代码。应采用渐进式迁移：

1. 在 Vue 3 环境中运行现有代码：首先确保项目能在 Vue 3 环境下正常运行。Vue 3 对大多数 Vue 2 选项式 API 有良好的兼容性。
2. 新组件采用组合式：所有新开发的组件，一律使用组合式 API（<script setup>）编写。
3. 在旧组件中混用：对于需要修改的旧组件，可以在其中局部使用组合式 API。Vue 3 允许在同一个组件中同时使用选项式和组合式（通过setup()选项）。你可以先将一部分紧密相关的逻辑抽离到setup()函数中。
4. 按需重构核心组件：当需要对某个复杂旧组件进行重大功能迭代时，趁此机会将其彻底重构为组合式。将其内部逻辑拆分为多个可复用的组合式函数。

5.3 组合式 API 的最佳实践与模式

1. 单一职责的组合式函数：每个组合式函数只做一件事，并且把它做好。例如useFetch只负责数据请求，useMouse只负责追踪鼠标。这保证了函数的高内聚和可复用性。
2. 使用ref而非reactive作为主要 API：如前所述，ref在组合式函数间传递更安全，且与 TS 集成更好。一个常见的模式是，即使管理对象状态，也使用ref：

   const formState = ref({ username: '', password: '' }); // 访问：formState.value.username

3. 善用computed和watch：将复杂的派生逻辑放入computed；将副作用（如请求、日志、DOM操作）放入watch或watchEffect。保持setup函数主体逻辑的纯净。
4. 组织setup函数内部的代码：虽然可以自由组织，但推荐一种清晰的模式：先声明响应式状态（ref,reactive），然后是计算属性（computed），接着是普通函数（方法），最后是生命周期和侦听器（onMounted,watch）。相关的逻辑块可以用空行分隔。

6. 常见问题与实战排坑指南

在实际开发中，从选项式转向组合式会遇到一些典型的“坑”。这里记录一些高频问题和解决方案。

6.1 响应式丢失问题

问题场景：解构reactive对象，或将reactive对象的属性传入普通函数后，失去响应性。

const state = reactive({ count: 0 }); let { count } = state; // 错误！count 现在是普通值，失去响应性 setTimeout(() => { count++ }, 1000); // 不会触发视图更新 function passValue(val) { /* val 不是响应式的 */ } passValue(state.count); // 传入的是值，不是响应式引用

解决方案：

1. 始终通过state.count来访问和修改。
2. 如果需要解构并保持响应性，使用toRefs：

   const state = reactive({ count: 0, name: 'Vue' }); const { count, name } = toRefs(state); // 现在 count 和 name 都是 ref count.value++; // 有效！

3. 这也是推荐优先使用ref的原因之一，ref的.value属性在传递时总是需要显式操作，不容易被意外解构。

6.2 生命周期钩子的对应关系

选项式的生命周期钩子在组合式 API 中有对应的函数，它们需要从vue中导入并在setup中调用：

重要区别：组合式的生命周期钩子接受一个回调函数，并且可以多次调用同一个钩子。这允许你将不同逻辑的初始化代码放在不同的地方（例如，一个onMounted用于获取数据，另一个onMounted用于初始化图表库），而不是像选项式那样把所有代码都堆在一个mounted函数里。

6.3 访问组件实例与模板 Ref

在选项式中，通过this.$refs.myInput访问模板元素或子组件。在组合式中：

1. 声明模板 Ref：使用ref函数。

   <template> <input ref="inputRef" /> </template> <script setup> import { ref, onMounted } from 'vue'; const inputRef = ref(null); // 声明一个同名的 ref onMounted(() => { inputRef.value.focus(); // 在挂载后访问 DOM 元素 }); </script>

2. 访问子组件实例：同样使用ref，但子组件需要使用defineExpose显式暴露其方法或属性。

   <!-- Child.vue --> <script setup> import { ref } from 'vue'; const childMethod = () => { /* ... */ }; const childData = ref('data'); // 父组件只能访问到被暴露的内容 defineExpose({ childMethod, childData }); </script> <!-- Parent.vue --> <template> <Child ref="childRef" /> </template> <script setup> import { ref } from 'vue'; import Child from './Child.vue'; const childRef = ref(null); const callChildMethod = () => { childRef.value?.childMethod(); // 安全调用 console.log(childRef.value?.childData); }; </script>

6.4 与选项式组件或第三方库的互操作

有时你需要在使用组合式 API 的组件中与一个选项式组件（比如一个老旧的第三方组件）交互。

1. 使用defineOptions：在<script setup>中，你可以使用defineOptions来定义一些无法用组合式 API 定义的选项，如name,inheritAttrs, 或自定义选项。

   <script setup> import { defineOptions } from 'vue'; defineOptions({ name: 'MyComponent', inheritAttrs: false }); </script>

2. 使用useAttrs和useSlots：在组合式 API 中，无法直接访问this.$attrs和this.$slots。需要使用对应的组合式函数。

   import { useAttrs, useSlots } from 'vue'; const attrs = useAttrs(); const slots = useSlots();

从我个人的迁移和开发经验来看，组合式 API 初期的学习成本是存在的，尤其是思维模式的转变。但一旦跨越这个门槛，其带来的代码组织灵活性、逻辑复用能力和类型安全性的提升是巨大的。它让 Vue 组件不再是“黑盒”，而是一组可以清晰追溯、自由组合的 JavaScript 函数集合。对于长期维护和迭代的中大型项目，这种收益是决定性的。因此，我的建议是，无论新老项目，都应将组合式 API 作为未来的主要发展方向。