UmiJS 4 中使用 Qiankun 微前端插件的正确方式

背景介绍

在使用 UmiJS 4 构建项目时，很多开发者会遇到微前端集成的问题。特别是从 UmiJS 3 升级到 UmiJS 4 的过程中，关于 Qiankun 插件的使用方式发生了重要变化，这导致了不少开发者在迁移过程中遇到报错和困惑。

问题现象

开发者在使用 UmiJS 4.1.5 版本时，按照传统方式安装 @umijs/plugin-qiankun 插件（版本 2.25.2）后，运行项目会出现以下典型错误：

1. Node.js 14 环境下报错："Cannot read property 't' of undefined"
2. Node.js 16 环境下报错：插件兼容性问题

这些错误提示表明插件与 UmiJS 4 版本存在兼容性问题。

原因分析

经过深入分析，发现根本原因是：

• 在 UmiJS 3 时代，Qiankun 微前端功能是通过独立的 @umijs/plugin-qiankun 插件提供的
• 到了 UmiJS 4，微前端功能被整合到了核心插件包 @umijs/plugins 中
• 直接安装旧版独立插件会导致版本不兼容问题

正确解决方案

对于 UmiJS 4 项目，正确的 Qiankun 微前端集成方式应该是：

1. 卸载旧的独立插件（如果已安装）：

   npm uninstall @umijs/plugin-qiankun
   

2. 安装 UmiJS 4 的核心插件包：

   npm install @umijs/plugins
   

3. 在配置文件中使用正确的插件路径：

   export default {
     plugins: ['@umijs/plugins/dist/qiankun'],
     qiankun: {
       slave: {},
     },
   }
   

版本兼容性说明

开发者需要注意以下版本对应关系：

• UmiJS 3.x 系列：使用 @umijs/plugin-qiankun 独立插件
• UmiJS 4.x 系列：使用 @umijs/plugins 中的内置 Qiankun 功能

最佳实践建议

1. 始终检查官方文档获取最新的插件使用方式
2. 在升级 UmiJS 大版本时，注意相关插件的兼容性变化
3. 使用 Node.js 16 或更高版本以获得更好的兼容性
4. 在配置微前端时，确保主应用和子应用的 UmiJS 版本一致

通过遵循这些指导原则，开发者可以避免常见的兼容性问题，顺利地在 UmiJS 4 项目中实现 Qiankun 微前端架构。