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

前言

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

一、实现方法

1. 模块联邦基础配置

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

Vue2 项目配置

// vue2-app/vue2.config.js
module.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.js
module.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.js
export 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.js
function 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.vue
export default {
  methods: {
    click() {
      this.$emit('btnClick');
      this.$emit('onBtnClick');
    }
  }
};

二、常见问题与解决方案

1. 模块加载错误

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

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

方法一：使用 bootstrap.js

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

方法二：检查环境变量

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

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

# .env.production
NODE_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.js
export 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();
    }
  };
}