JeecgBoot低代码平台 Qiankun 微前端集成指南：主应用配置全流程

JeecgBoot AI专题研究 | JeecgBoot低代码微前端架构落地实践

微前端解决了什么问题？

当 JeecgBoot低代码项目发展到一定规模，单体前端的弊端开始显现：模块耦合严重、构建时间激增、团队协作困难。微前端架构允许将不同业务模块拆分为独立的子应用，各自开发、独立部署，通过 Qiankun 框架在运行时动态组合。

本文聚焦于如何将 JeecgBoot-Vue3 配置为 Qiankun 微前端的主应用（基座），接管路由分发和子应用生命周期管理。

第一步：安装 Qiankun 依赖

在 JeecgBoot低代码主应用项目中安装 Qiankun：

bash 复制代码

pnpm add qiankun

第二步：配置子应用注册信息

JeecgBoot 已经预置了 Qiankun 集成的代码框架，只需要取消注释并配置三个核心文件：

src/qiankun/apps.ts --- 子应用注册表

在这个文件中定义每个微应用的元数据：

typescript 复制代码

const apps = [
  {
    name: 'qiankun-app',          // 子应用唯一标识
    entry: '//localhost:8001',     // 子应用入口地址
    container: '#subapp-viewport', // 挂载容器
    activeRule: '/qiankun-app',    // 路由激活规则
  },
];

src/qiankun/state.ts --- 全局状态管理

建立主应用与子应用之间的数据共享通道，用于传递用户信息、权限数据、主题配置等全局状态。

src/qiankun/index.ts --- 注册与启动

注册所有子应用并配置生命周期钩子（加载前、挂载后、卸载后等），这是微前端运行时的核心调度逻辑。

第三步：配置环境变量

不同环境下子应用的入口地址不同，需要在环境变量文件中分别配置。

开发环境 .env.development：

properties 复制代码

VITE_APP_SUB_qiankun-app = '//localhost:8001/qiankun-app'

生产环境 .env.production：

properties 复制代码

VITE_APP_SUB_qiankun-app = '[生产域名]/qiankun-app'

同时，在环境变量中开启 Qiankun 全局开关：

properties 复制代码

VITE_GLOB_APP_OPEN_QIANKUN=true

第四步：子应用侧的适配要求

子应用要接入 JeecgBoot低代码主应用，需要满足以下条件：

1. 配置运行时公共路径

创建 public-path.js 文件，确保子应用在 Qiankun 沙箱环境下能正确加载静态资源：

javascript 复制代码

if (window.__POWERED_BY_QIANKUN__) {
  __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
}

2. 导出生命周期函数

子应用必须导出以下四个生命周期函数供主应用调用：

bootstrap() --- 初始化，仅在首次加载时调用
mount() --- 挂载，每次进入子应用时调用
unmount() --- 卸载，每次离开子应用时调用
update() --- 更新，主应用传递数据变更时调用

3. 构建输出配置

子应用的 vue.config.js 需要配置 UMD 格式输出，并开启 CORS 跨域头：

javascript 复制代码

module.exports = {
  output: {
    library: 'qiankun-app',
    libraryTarget: 'umd',
  },
  devServer: {
    headers: { 'Access-Control-Allow-Origin': '*' },
  },
};

实践中的注意事项

样式隔离 ：Qiankun 默认的沙箱机制可以隔离 JS 全局变量，但 CSS 隔离需要额外配置 strictStyleIsolation 或 experimentalStyleIsolation
路由冲突：主应用和子应用的路由前缀不能重叠，建议每个子应用使用独立的路由命名空间
通信机制 ：简单场景使用 Qiankun 内置的 initGlobalState，复杂场景可以引入 EventBus 或状态管理库

总结

JeecgBoot低代码平台对 Qiankun 微前端的集成已经做了大量预置工作，开发者只需取消注释、配置环境变量即可快速启用。微前端架构特别适合多团队协作的大型项目，能够在保持整体统一性的同时给予各业务团队充分的技术自主权。

本文为 JeecgBoot AI 专题研究系列文章。