![image](https://developer.qcloudimg.com/http-save/yehe-1209475/a8cce9eec221e40386106a6f5b8cbc60.png)

## 前言

你好，我是喵喵侠，是一名前端开发。

即便到了 2026 年，我依然能在很多维护中的老项目里看到 Options API 的身影。很多同学在迁移到 Vue 3 时，往往只是机械地把代码从 `data`​ 搬到 `ref`​，从 `methods`​ 搬到普通的 `function`。

这种“换汤不换药”的做法，不仅没能发挥出 Composition API 的威力，反而因为代码逻辑散乱，导致项目在中后期变得难以维护。今天我想聊聊在这两套 API 转换过程中我踩过的坑，以及目前我认为最稳健的写法。

## 典型混用导致的痛点

在 Options API 中，我们的思维是**按属性组织**的。

当你维护一个老项目时，你会发现一个尴尬的现象：为了改动一个“搜索功能”，你需要先在 `data`​ 里找变量，再跳到 `methods`​ 里找逻辑，最后去 `computed` 里看联动。如果一个组件有 500 行，你的滚动条就会像蹦迪一样上下横跳。

这种“碎片化”的组织方式，在逻辑简单时很清晰，但在业务逻辑高度复杂的今天，它成了阻碍代码复用的最大障碍。

## `script setup`：现在的唯一选择

很多初学者还在纠结 `setup()`​ 函数和 `<script setup>`​ 到底用哪个。在 2026 年，这个问题的答案很明确：​**无脑使用**  **​`<script setup>`​** 。

#### 1. 样板代码对比

`setup()`​ 函数需要手动 `return` 每一个变量和方法，否则模板无法访问。这不仅冗余，还容易漏写导致报错。

```javascript
<script>
export default {
  setup() {
    const count = ref(0);
    const increment = () => count.value++;
    return { count, increment }; // 必须手动返回
  }
}
</script>
```

而 `<script setup>` 声明的变量在模板中直接可用，且编译器能更好地进行静态分析和代码压缩。

```javascript
<script setup>
import { ref } from 'vue';

const count = ref(0);
const increment = () => count.value++;
</script>
```

## 逻辑组织：使用 **Composables** 拆分

Composition API 的精髓不在于写在 `setup`​ 里，而在于​**逻辑提取**​。我最推荐的组织方式是：​**组件只负责“拼装”，Composables 负责“实现”** 。

#### 1. 推荐的项目结构

不要在 `.vue` 文件里写几百行的逻辑。你应该按功能维度进行拆分：

```javascript
// src/composables/use-user-auth.ts
import { ref, computed } from 'vue';

export function useUserAuth() {
  const userInfo = ref(null);
  const isLoggedIn = computed(() => !!userInfo.value);
  
  const login = async () => { /* ... */ };
  
  return { userInfo, isLoggedIn, login };
}
```

在组件中引入：

```javascript
<script setup>
import { useUserAuth } from '@/composables/use-user-auth';

const { userInfo, isLoggedIn, login } = useUserAuth();
</script>
```

这种写法让逻辑变成了“乐高积木”，不仅可以在多个组件复用，测试起来也极为方便。

## 避坑指南：常见错误

在迁移过程中，有两个重灾区：变量定义的选型和生命周期的理解。

#### 1. `ref`​ VS `reactive`的误用

很多新手喜欢用 `reactive`​ 定义一切，因为这样不用写 `.value`。但这会带来两个致命问题：

1. **解构丢失响应性**​：`const { name } = reactive({ name: 'miao' })`​ 之后，`name` 就失去了响应性。
2. **无法直接赋值**​：你不能给 `reactive` 对象重新赋值一个新对象，否则旧的引用会失效。

**建议**​：始终使用 `ref`​。虽然 `.value` 看起来有点繁琐，但它在类型检查和响应性追踪上更可靠。

#### 2. 生命周期顺序问题

在 Composition API 中，没有 `beforeCreate`​ 和 `created`​。因为 `setup` 本身就在这两个钩子之间执行。

如果你需要在组件初始化时请求数据，直接在 `script setup`​ 顶层写即可，不需要非得塞进 `onMounted`，除非你需要访问 DOM 节点。

## 迁移 checklist

如果你正准备把一个 Options API 组件重构为 Composition API，可以参考以下步骤：

#### 1. 转换步骤

- 将 `data`​ 转换为 `ref`​ 或 `shallowRef`。
- 将 `computed`​ 原封不动搬进 `computed()` 函数。
- 将 `methods`​ 转换为普通的 `const` 函数。
- 将 `watch`​ 转换为 `watch`​ 或 `watchEffect`。
- 将生命周期钩子（如 `mounted`​）转换为 `onMounted`。

#### 2. 代码对比示例

> 🛑 ​**输入纠错提示**​：在 Options API 中使用 `this.$set` 已经不再必要，Vue 3 的 Proxy 能够自动处理新增属性。

**重构前 (Options API)** ：

```javascript
export default {
  data() {
    return { status: 'idle' };
  },
  methods: {
    updateStatus() {
      this.status = 'active';
    }
  }
}
```

**重构后 (Composition API)** ：

```javascript
const status = ref('idle');
const updateStatus = () => {
  status.value = 'active';
};
```

## 总结

从 Options API 迁移到 Composition API，本质上是\*\*从“配置式”向“逻辑式”\*\*的思维转变。不要只是简单地搬运代码，而要学会利用 Composables 将散乱的逻辑聚合。记住：代码量的减少不是目的，逻辑的可维护性和清晰的响应性追踪才是我们追求的目标。只要避开 `reactive`​ 的坑并坚持使用 `script setup`，你的 Vue 3 开发体验将会提升一个量级。

‍


即便到了 2026 年，我依然能在很多维护中的老项目里看到 Options API 的身影。很多同学在迁移到 Vue 3 时，往往只是机械地把代码从 data​ 搬到 ref​，从 methods​ 搬到普通的 function。

Vue 3 从 Options API 到 Composition API：我踩过的坑和现在最推荐的写法

前端

Vue3迁移指南：从OptionsAPI到CompositionAPI的最佳实践。详解scriptsetup优势、逻辑组织技巧，避免reactive陷阱，提供迁移checklist。帮助开发者提升代码复用性和可维护性，发挥Vue3真正威力。

编译器

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Vue 3 从 Options API 到 Composition API：我踩过的坑和现在最推荐的写法-腾讯云开发者社区-腾讯云

Vue 3 从 Options API 到 Composition API：我踩过的坑和现在最推荐的写法

Vue 3 从 Options API 到 Composition API：我踩过的坑和现在最推荐的写法

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐