Vue3 项目中集成 Vue2 组件的实践与经验总结

前言

在一个 Vue3 项目中使用 Vue2 组件可能会遇到一些挑战。本文将分享从 Vue2 迁移到 Vue3 的实践经验，重点描述在模块联邦（Module Federation）下集成 Vue2 组件的过程及相关问题。

一、实现方法

1. 模块联邦基础配置

在项目初期，我们需要通过模块联邦来实现 Vue2 组件与 Vue3 项目的无缝集成。以下是关键配置步骤：

Vue2 项目配置

// vue2-app/vue2.config.jsmodule.exports = {  plugins: [    new ModuleFederationPlugin({      name: 'vue2App',      filename: 'remoteEntry.js',      library: { type: 'var', name: 'vue2App' },      exposes: {        './vue2': './node_modules/vue/dist/vue',        './Button': './src/components/Button'      }    })  ]}

Vue3 项目配置

// vue3-app/webpack.config.jsmodule.exports = {  plugins: [    new ModuleFederationPlugin({      name: 'vue3App',      filename: 'remoteEntry.js',      remotes: {        vue2App: 'vue2App@http://localhost:3001/remoteEntry.js'      }    })  ]}

2. 组件集成方案

在 Vue3 项目中集成 Vue2 组件的关键在于实现两者的无缝对接。以下是具体实现方法：

1.1 单独挂载组件

在 Vue3 组件中直接使用 Vue2 组件可能会遇到问题。例如：

这种方式不适用。需要通过手动创建 DOM 节点来实现组件挂载。

1.2 使用挂载函数

在 utils.js 中，创建一个通用函数来挂载 Vue2 组件：

// utils.jsexport function vue2ToVue3(WrapperComponent, wrapperId) {  let vm;  return {    mounted() {      const slots = bindSlotContext(this.$slots, this.__self);      vm = new Vue2({        render: createElement => {          return createElement(WrapperComponent, {            on: this.$attrs,            attrs: this.$attrs,            props: this.$props,            scopedSlots: this.$scopedSlots          }, slots);        }      });      vm.$mount(`#${wrapperId}`);    },    props: WrapperComponent.props,    render() {      vm && vm.$forceUpdate();    }  };}

1.3 组件使用示例

在 Vue3 组件中使用挂载函数：

1.4 核心工具函数

utils.js 中的 bindSlotContext 函数用于将 Vue 组件的插槽上下文传递给挂载的 Vue2 组件：

// utils.jsfunction bindSlotContext(target = {}, context) {  return Object.keys(target).map(key => ({    vnode: target[key],    vnode.context = context  }));}

2. Vue2 组件开发

2.1 组件结构

一个典型的 Vue2 组件可能如下：

2.2 组件暴露

确保 Vue2 组件通过模块联邦正确暴露：

// src/components/Button.vueexport default {  methods: {    click() {      this.$emit('btnClick');      this.$emit('onBtnClick');    }  }};

二、常见问题与解决方案

1. 模块加载错误

错误信息：`Uncaught Error: Shared module is not available for eager consumption`

这种错误通常发生在模块加载过程中。解决方案是：

方法一：使用 bootstrap.js

// bootstrap.jsimport { createApp } from 'vue';import App from './App.vue';import router from './router';createApp(App)  .use(router)  .mount('#app');

方法二：检查环境变量

在项目根目录下创建以下 .env 文件：

# .env.developmentNODE_ENV = 'development'VUE_APP_API_ENV = 'dev'

# .env.productionNODE_ENV = 'production'VUE_APP_API_ENV = 'prod'

方法三：使用 cross-env 工具

cross-env NODE_ENV=development yarn serve

2. 第三方库兼容性问题

Vue3 不支持的库

在 Vue2 组件库中使用 Element UI 的话，在 Vue3 项目中需要切换到 Element Plus：

// package.json{  "dependencies": {    "element-plus": "^2.0.0"  }}

自定义组件支持

对于自定义或封装的组件，可以按照以下方式使用：

// utils.jsexport function vue2ToVue3(WrapperComponent, wrapperId) {  let vm;  return {    mounted() {      const slots = bindSlotContext(this.$slots, this.__self);      vm = new Vue2({        render: createElement => {          return createElement(WrapperComponent, {            on: this.$attrs,            attrs: this.$attrs,            props: this.$props,            scopedSlots: this.$scopedSlots          }, slots);        }      });      vm.$mount(`#${wrapperId}`);    },    props: WrapperComponent.props,    render() {      vm && vm.$forceUpdate();    }  };}