从Options API到Composition API：如何平滑迁移一个存量Vue 2项目？

admin
Mon, 08 Sep 2025 07:56:16 +0000
Vue, api, composition, options

好的，让我们开始吧。 Vue 2 项目迁移到 Composition API 的平滑过渡方案 大家好，今天我们来聊聊如何将一个现有的 Vue 2 项目平滑地迁移到 Composition API。这是一个非常现实的问题，因为 Vue 3 已经发布很久了，而 Composition API 带来了很多优势，包括更好的代码组织、更强的逻辑复用能力以及更好的类型推断。 迁移一个大型项目并非一蹴而就，需要仔细规划和逐步实施。我们的目标是在尽可能不影响现有功能的情况下，逐步引入 Composition API，最终完成整个项目的迁移。 1. 迁移前的准备工作 在开始迁移之前，我们需要做好以下准备工作： 升级 Vue CLI: 如果你的项目是基于 Vue CLI 创建的，请确保你使用的是最新版本的 Vue CLI。这有助于简化迁移过程，并提供更好的 TypeScript 支持。 npm install -g @vue/cli # 或 yarn global add @vue/cli 安装 Vue 3 兼容包: 为了在 Vue 2 项目中使用 Composition API，我们需要安装 @vue/ …

继续阅读“从Options API到Composition API：如何平滑迁移一个存量Vue 2项目？”

The post 从Options API到Composition API：如何平滑迁移一个存量Vue 2项目？ first appeared on 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座.

好的，让我们开始吧。

Vue 2 项目迁移到 Composition API 的平滑过渡方案

大家好，今天我们来聊聊如何将一个现有的 Vue 2 项目平滑地迁移到 Composition API。这是一个非常现实的问题，因为 Vue 3 已经发布很久了，而 Composition API 带来了很多优势，包括更好的代码组织、更强的逻辑复用能力以及更好的类型推断。

迁移一个大型项目并非一蹴而就，需要仔细规划和逐步实施。我们的目标是在尽可能不影响现有功能的情况下，逐步引入 Composition API，最终完成整个项目的迁移。

1. 迁移前的准备工作

在开始迁移之前，我们需要做好以下准备工作：

升级 Vue CLI: 如果你的项目是基于 Vue CLI 创建的，请确保你使用的是最新版本的 Vue CLI。这有助于简化迁移过程，并提供更好的 TypeScript 支持。

npm install -g @vue/cli
# 或
yarn global add @vue/cli

安装 Vue 3 兼容包: 为了在 Vue 2 项目中使用 Composition API，我们需要安装 @vue/composition-api 插件。

npm install @vue/composition-api
# 或
yarn add @vue/composition-api

在 main.js 中引入并使用插件: 在 Vue 2 项目的入口文件 main.js 中，我们需要引入并使用 @vue/composition-api 插件。

import Vue from 'vue';
import App from './App.vue';
import VueCompositionAPI from '@vue/composition-api';

Vue.use(VueCompositionAPI);

new Vue({
  render: h => h(App),
}).$mount('#app');

TypeScript 支持: 如果你的项目尚未使用 TypeScript，强烈建议引入 TypeScript。Composition API 与 TypeScript 结合使用可以发挥更大的威力，提供更好的类型安全性和代码提示。

vue add typescript

2. 迁移策略：逐步引入 Composition API

我们的迁移策略是逐步引入 Composition API，而不是一次性重写所有组件。这意味着我们将选择一些相对独立的组件，先将其迁移到 Composition API，然后再逐步扩展到整个项目。

以下是一些建议的迁移步骤：

1. 选择合适的组件: 选择一些小型、独立的组件作为首批迁移对象。这些组件最好没有太多的依赖关系，并且逻辑相对简单。例如，一些展示性的组件、表单项组件等。

2. 创建 setup 函数: 在选定的组件中，创建一个 setup 函数。这是 Composition API 的核心，所有逻辑都将在 setup 函数中编写。

3. 迁移 data 属性: 将 data 属性中的数据迁移到 setup 函数中，并使用 ref 或 reactive 进行包装。

4. 迁移 methods 属性: 将 methods 属性中的方法迁移到 setup 函数中。

5. 迁移 computed 属性: 将 computed 属性迁移到 setup 函数中，并使用 computed 函数进行包装。

6. 迁移 watch 属性: 将 watch 属性迁移到 setup 函数中，并使用 watch 函数进行包装。

7. 返回响应式数据和方法: 在 setup 函数中，返回所有需要在模板中使用的响应式数据和方法。

8. 测试和验证: 完成迁移后，进行充分的测试和验证，确保组件的功能正常。

3. 代码示例：迁移一个简单的计数器组件

让我们通过一个简单的计数器组件来演示如何进行迁移。

Vue 2 Options API 版本:



Count: {{ count }}
Increment




export default {
  data() {
    return {
      count: 0,
    };
  },
  methods: {
    increment() {
      this.count++;
    },
  },
};


迁移到 Composition API 版本:



Count: {{ count }}
Increment




import { ref } from '@vue/composition-api';

export default {
  setup() {
    const count = ref(0);

    const increment = () => {
      count.value++;
    };

    return {
      count,
      increment,
    };
  },
};


代码解释:

我们首先从 @vue/composition-api 导入了 ref 函数。

在 setup 函数中，我们使用 ref(0) 创建了一个响应式的 count 变量，初始值为 0。

我们创建了一个 increment 函数，用于增加 count 的值。注意，我们需要使用 count.value 来访问 count 的值。

最后，我们使用 return 语句返回了 count 和 increment，以便在模板中使用。

4. 处理 Options API 和 Composition API 的混合使用

在迁移过程中，不可避免地会遇到 Options API 和 Composition API 混合使用的情况。Vue 2 + @vue/composition-api 允许你在同一个组件中同时使用这两种 API。

Options API 访问 Composition API:

在 Options API 中，可以通过 this 访问 setup 函数中返回的响应式数据和方法。



Count: {{ count }}
Increment




import { ref } from '@vue/composition-api';

export default {
  data() {
    return {
      message: 'Hello',
    };
  },
  methods: {
    printMessage() {
      console.log(this.message);
      console.log(this.count); // 访问 Composition API 中的 count
    },
  },
  setup() {
    const count = ref(0);

    const increment = () => {
      count.value++;
    };

    return {
      count,
      increment,
    };
  },
};


Composition API 访问 Options API:

在 Composition API 中，可以使用 this 访问 Options API 中的数据和方法。但是，不建议这样做，因为它会增加代码的复杂性，并降低可维护性。尽量避免在 setup 函数中直接访问 this。



Count: {{ count }}
Increment




import { ref } from '@vue/composition-api';

export default {
  data() {
    return {
      message: 'Hello',
    };
  },
  methods: {
    printMessage() {
      console.log(this.message);
    },
  },
  setup() {
    const count = ref(0);

    const increment = () => {
      count.value++;
      this.printMessage(); // 访问 Options API 中的 printMessage (不推荐)
    };

    return {
      count,
      increment,
    };
  },
};


建议: 尽量避免在 Options API 和 Composition API 之间相互访问。如果需要在两者之间共享数据或方法，可以考虑使用 provide/inject 或者 Vuex 等状态管理方案。

5. 处理生命周期钩子

Composition API 提供了新的生命周期钩子函数，与 Options API 中的生命周期钩子函数有所不同。

Options API | Composition API | 说明
beforeCreate | setup | 在组件实例创建之前调用。
created | setup | 在组件实例创建之后调用。
beforeMount | onBeforeMount | 在挂载开始之前被调用。
mounted | onMounted | 在挂载完成后被调用。
beforeUpdate | onBeforeUpdate | 在数据更新之前被调用。
updated | onUpdated | 在数据更新之后被调用。
beforeDestroy | onBeforeUnmount | 在实例销毁之前调用。
destroyed | onUnmounted | 在实例销毁之后调用。
activated | onActivated | 被 keep-alive 缓存的组件激活时调用。
deactivated | onDeactivated | 被 keep-alive 缓存的组件停用时调用。
errorCaptured | onErrorCaptured | 当捕获一个来自子孙组件的错误时被调用。
renderTracked | onRenderTracked | 在渲染函数追踪依赖时调用。
renderTriggered | onRenderTriggered | 在渲染函数被触发时调用。

代码示例:



Count: {{ count }}
Increment




import { ref, onMounted, onBeforeUnmount } from '@vue/composition-api';

export default {
  setup() {
    const count = ref(0);

    const increment = () => {
      count.value++;
    };

    onMounted(() => {
      console.log('Component mounted');
    });

    onBeforeUnmount(() => {
      console.log('Component will unmount');
    });

    return {
      count,
      increment,
    };
  },
};


注意:

Composition API 中的生命周期钩子函数需要在 setup 函数中调用。

在 onBeforeUnmount 中，我们需要手动清理副作用，例如取消订阅事件、清除定时器等。

6. 使用 Vuex 进行状态管理

如果你的项目使用了 Vuex 进行状态管理，你需要确保 Vuex 与 Composition API 兼容。

Vuex 4: Vuex 4 已经完全支持 Composition API。你可以使用 useStore hook 来访问 Vuex store。

import { useStore } from 'vuex';

export default {
  setup() {
    const store = useStore();

    const count = computed(() => store.state.count);

    const increment = () => {
      store.commit('increment');
    };

    return {
      count,
      increment,
    };
  },
};

Vuex 3: 如果你的项目仍然使用 Vuex 3，你需要安装 @vue/composition-api 提供的 mapState、mapGetters、mapActions 和 mapMutations 函数。

import { mapState, mapGetters, mapActions, mapMutations } from '@vue/composition-api';

export default {
  setup() {
    const { count } = mapState(['count']);
    const { doubleCount } = mapGetters(['doubleCount']);
    const { increment } = mapActions(['increment']);
    const { setCount } = mapMutations(['setCount']);

    return {
      count,
      doubleCount,
      increment,
      setCount,
    };
  },
};

7. 使用 Provide/Inject 进行依赖注入

Composition API 提供了 provide 和 inject 函数，用于进行依赖注入。这与 Options API 中的 provide 和 inject 选项类似，但使用方式更加灵活。

Provide:

import { provide } from '@vue/composition-api';

export default {
  setup() {
    const message = ref('Hello from parent');

    provide('message', message);

    return {};
  },
};

Inject:

import { inject } from '@vue/composition-api';

export default {
  setup() {
    const message = inject('message');

    return {
      message,
    };
  },
};

8. 第三方库的兼容性

在迁移过程中，你需要注意第三方库的兼容性。一些第三方库可能尚未完全支持 Composition API，或者需要进行一些配置才能正常工作。

Vue Router: Vue Router 4 已经完全支持 Composition API。你可以使用 useRouter 和 useRoute hooks 来访问 router 实例和 route 对象。

UI 库: 大多数主流的 UI 库，例如 Element UI、Ant Design Vue 等，都提供了对 Composition API 的支持。请查阅相关文档，了解如何在使用 Composition API 的组件中使用这些 UI 库。

9. 工具和辅助函数

为了简化迁移过程，你可以创建一些工具和辅助函数。

Options API to Composition API 代码转换工具: 可以使用一些现有的代码转换工具，例如 vue-codemod，来自动将 Options API 代码转换为 Composition API 代码。

自定义 hooks: 将一些常用的逻辑封装成自定义 hooks，以便在不同的组件中复用。

10. 注意事项

保持代码风格一致: 在迁移过程中，尽量保持代码风格一致。这有助于提高代码的可读性和可维护性。

充分测试: 每次完成迁移后，进行充分的测试，确保组件的功能正常。

逐步迭代: 不要试图一次性完成所有迁移工作。将迁移过程分解为多个小的迭代，逐步完成。

团队协作: 如果你的项目由多个开发人员共同维护，请确保所有开发人员都了解 Composition API 的使用方法，并遵循统一的迁移策略。

总结与展望

将 Vue 2 项目迁移到 Composition API 是一个复杂但值得的过程。通过逐步引入、充分测试和团队协作，我们可以平滑地完成迁移，并享受到 Composition API 带来的诸多好处。

记住，迁移是一个迭代的过程，并非一蹴而就。重要的是制定清晰的迁移策略，并逐步实施。

关于代码组织和可维护性的一些思考

Composition API 更倾向于以功能组织代码，使得相关功能的代码更加内聚，提高了代码的可读性和可维护性。 此外，Composition API 可以更好地与 TypeScript 结合，提供更强的类型推断，进一步提升代码质量。