JeecgBoot接入Qiankun微前端：子应用改造实操指南

在做企业级前端架构的时候，我接手过不少“把某个老系统塞进微前端壳子”的活。大多数情况下，塞进去的不是一个页面，而是一个完整的业务应用。JeecgBoot 作为开源的 Java 低代码平台，本身自带了完整的用户体系、菜单权限、表单设计器和代码生成器，用拖拉拽的方式就能快速搭出一套中后台管理系统。

但这套东西真正要作为子应用接入 Qiankun 微前端架构时，事情就不像“把入口改成挂载函数”那么简单了。JeecgBoot 内部有动态路由、登录拦截、Axios 封装、公共前缀代理、低代码表单动态渲染，这些组件在独立跑的时候一切正常，一旦被主应用接管，任何一环没有处理好，都会变成白屏、路由错乱、接口 401、样式被污染。

这篇文章就从实操角度，完整讲清楚 JeecgBoot 低代码平台作为 Qiankun 子应用的接入过程。包括 Vue2 + webpack 和 Vue3 + Vite 两种项目形态的改造方式，主应用侧的注册配置，登录态联动、公共依赖与静态资源的处理，最后附上我在实际项目里遇到过的典型问题和排查思路。如果你正准备把低代码平台接进现有的微前端体系，这篇文章应该能帮你省掉几次通宵排查。

1. 拆清楚 JeecgBoot 和 Qiankun 的适配关系

1.1 微前端 + 低代码，到底解决了什么问题

微前端解决的是“多个团队、多个技术栈、多个独立部署的应用怎么共用一个门户”的问题。Qiankun 是目前使用最广的方案，它在 single-spa 基础上封装了样式隔离、JS 沙箱、预加载等能力，对老项目的接入相对友好。你可以把一个单体前端拆成多个独立开发、独立部署的应用，由主应用作为壳统一调度，子应用按路由加载。

低代码平台解决的是“大量重复 CRUD 页面怎么写更快”的问题。JeecgBoot 提供了在线表单设计器、在线报表、代码生成器、工作流等功能，后台管理系统里常见的增删改查页面，通过拖拽配置就能生成，效率比手写提高非常多。

把两者结合起来，其实是很多中大型企业正在做的事：主应用承载统一的工作台入口、门户框架和全局登录态，低代码平台作为子应用，专门承担快速交付的业务模块。开发人员在 JeecgBoot 里拖出页面，打包成子应用，接入主应用菜单，用户就能通过门户统一入口访问新功能，不再需要在不同的域名和系统之间来回切换。

对技术团队来说，这个组合最直接的收益是：主应用不用跟着低代码平台的版本迭代走，低代码平台也不受主应用技术栈的约束，两边各自发版，互不阻塞。

1.2 JeecgBoot 前端项目的两种形态

接入 Qiankun 之前，先要弄清楚你手里的是哪个 JeecgBoot 前端版本。因为这两个版本对应的改造方式完全不同，走错了路真的会白干几天。

JeecgBoot 前端现在常见两条线。一条是 jeecgboot-vue2，基于 Vue 2.6 + Vue CLI/webpack + Ant Design Vue 1.x + Vuex，这套老版本在存量项目里用得不少。另一条是官方后来推出的 jeecgboot-vue3，基于 Vue 3 + Vite + Ant Design Vue 3.x + TypeScript + Pinia，是现在新项目的主要方向。

Qiankun 对 webpack 项目的支持非常成熟，只需要改几个配置就能接入。但 Vite 项目因为是原生 ESM 的构建机制，Qiankun 官方原生不支持，需要借助 vite-plugin-qiankun 这种插件来桥接。所以“你的 JeecgBoot 是 Vue2 还是 Vue3”这个问题的答案，直接决定了后续的整改路径。

我这次实际项目里对接的是一个老版本 jeecgboot-vue2，主应用是 Vue3 + Vite。两套技术栈混在一起，踩了不少版本兼容的坑。这篇文章会把两种形态的改造都讲一遍，方便你对号入座。

1.3 理解 JeecgBoot 的启动链路

拿到 JeecgBoot 前端工程后，不要急着改动，先花半天把 main.js 逐行走一遍。这个工程的启动链路比普通 Vue 项目复杂得多，关键步骤包括：创建 Vue 实例、注册全局组件和插件、初始化 Vuex/Pinia 状态、创建 Vue Router 实例、请求后端接口获取用户信息、拉取菜单权限列表、动态注册路由、最后挂载根组件。

Qiankun 接入的关键在于第 4 步和第 7 步。Qiankun 要求子应用必须导出 bootstrap、mount、unmount 三个生命周期钩子，并且把“创建应用实例”这个动作放到 mount 里执行，而不是在入口文件里直接自动挂载。也就是说，原来“启动即挂载”的逻辑，要改造成“被 Qinkun 调用时才挂载”的模式。

JeecgBoot 的动态路由也是一个大坑。它的菜单不是前端写死的，而是后端根据用户权限返回的权限列表，前端再通过 addRoute 动态注册。这导致的结果是：子应用被嵌入主应用后，如果初始化顺序没处理好，菜单可能拉不到，路由也可能注册失败，页面一片空白。

2. 接入前先做好的工程准备

2.1 版本选型和环境清单

接入前先把自己这边的环境梳理清楚。这里有一份我当时实际使用的环境清单，可以参考一下：

接入前先把两个项目都独立跑通，这是最基础的前提。很多同学一上来就急着改 Qinkun 配置，结果子应用本身都无法正常启动，后面排查起来特别混乱。我在做的时候，先是把 JeecgBoot 前端单独启动，确认后端接口能通、登录页能进、页面能正常渲染，然后再开始动主应用那侧。

2.2 主应用侧需要提前准备什么

主应用这边，Qiankun 的注册逻辑一般会集中在一个微前端配置模块里。先把最基础的子应用注册搭起来，再考虑后面的样式隔离、预加载等增强配置。

import { registerMicroApps, start } from 'qiankun'; registerMicroApps([ { name: 'jeecgboot', entry: '//localhost:3001', container: '#subapp-viewport', activeRule: '/jeecg', props: { token: getToken(), userInfo: getUserInfo(), }, } ]); start({ prefetch: true, sandbox: { experimentalStyleIsolation: true, }, });

这里我提前做了三件事：一是规划好子应用的 activeRule，我用的是 /jeecg，这样主应用路由里 /jeecg 开头的地址都会落到子应用容器；二是准备了一个承载子应用的容器组件，里面就是一个带 id 的 div；三是通过 props 把主应用的 token 和用户信息传给了子应用，为后续登录态打通做好准备。

承载子应用的容器组件很简单，比如 SubAppContainer.vue：

<template> <div id="subapp-viewport" /> </template>

主应用路由里对应配置：

{ path: '/jeecg/*', name: 'JeecgBootSubApp', component: () => import('@/views/SubAppContainer.vue'), }

到这一步，主应用侧能做的准备工作基本就绪。

3. 子应用改造：JeecgBoot 接入的核心实操

3.1 基于 Vue 2 + webpack 的经典改造方式

如果你是老版的 jeecgboot-vue2，改造步骤可以概括为：配置打包格式 + 暴露生命周期。具体来说分三步。

第一步，修改 vue.config.js，让子应用能被正确加载为 UMD 库，并设置一个明确的全局变量名：

const packageName = require('./package.json').name; module.exports = { publicPath: '/jeecg/', devServer: { port: 3001, headers: { 'Access-Control-Allow-Origin': '*', }, historyApiFallback: true, }, configureWebpack: { output: { library: `${packageName}-[name]`, libraryTarget: 'umd', jsonpFunction: `webpackJsonp_${packageName}`, }, }, };

这里有两个容易被忽略的配置。publicPath 设成 /jeecg/，是为了让子应用打包出来的 JS、CSS、图片资源都从 /jeecg/js/xxx.js 这种路径去加载，避免部署到主应用域名下以后资源 404。headers 里的 Access-Control-Allow-Origin: *，是让主应用以 fetch 方式拉取子应用 HTML 和 JS 的时候，不被浏览器跨域策略拦截。jsonpFunction 也是 Qinkun 文档里重点提到的，如果主应用和子应用的 webpack jsonpFunction 重名，资源加载会互相干扰。

第二步，修改 main.js，把自动启动改造成生命周期接管模式。核心代码是这样：

import Vue from 'vue'; import App from './App.vue'; import router from './router'; import store from './store'; let instance = null; function render(props = {}) { const { container } = props; instance = new Vue({ router, store, render: h => h(App), }).$mount(container ? container.querySelector('#app') : '#app'); } if (!window.__POWERED_BY_QIANKUN__) { render(); } export async function bootstrap() { console.log('jeecgboot bootstrap'); } export async function mount(props) { render(props); } export async function unmount() { instance.$destroy(); instance.$el.innerHTML = ''; instance = null; }

window.POWERED_BY_QIANKUN是 Qiankun 在加载子应用时注入的全局标记。用这个变量区分“独立运行”和“被 Qiankun 加载”两种模式，独立运行时就正常自动挂载，被加载时就把控制权交给 mount 生命周期。

第三步，处理路由实例。JeecgBoot 默认可能是 history 模式，但在 Qiankun 里被挂载后，路由要跟着主应用的路径走。我建议直接把子应用的路由改成 hash 模式，省心省力：

const router = new VueRouter({ mode: 'hash', base: window.__POWERED_BY_QIANKUN__ ? '/jeecg/' : '/', routes, });

这样访问主应用 /jeecg/xxx 地址时，子应用内部实际路径是 /jeecg/#/xxx，路由的命名空间完全隔离开，不容易和主应用冲突。

3.2 基于 Vue 3 + Vite 的改造方式

再讲讲新版 jeecgboot-vue3 的接入。Vite 构建产物是原生 ESM 模块，Qiankun 基于 single-spa 拉取 HTML 后，对 ESM 的处理没有 webpack 那么直接，所以官方推荐使用 vite-plugin-qiankun 这个插件。

先安装依赖：

npm install vite-plugin-qiankun -D

然后在 vite.config.ts 里引入配置：

import qiankun from 'vite-plugin-qiankun'; export default defineConfig({ plugins: [ vue(), qiankun('jeecgboot-vue3', { useDevMode: true, }), ], server: { port: 3001, cors: true, origin: 'http://localhost:3001', }, });

插件参数里的第一个字符串是子应用名称，这个名称必须和主应用 registerMicroApps 里的 name 完全一致，否则生命周期识别不了。

main.ts 的改造思路和 Vue2 版本类似，只是 Vue 的 API 变了。用 renderWithQiankun 包裹生命周期，挂载方式从 new Vue 改成 createApp：

import { createApp } from 'vue'; import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/dist/helper'; import App from './App.vue'; import router from './router'; import pinia from './store'; let app: any = null; function render(props: any = {}) { const { container } = props; app = createApp(App); app.use(router); app.use(pinia); app.mount(container ? container.querySelector('#app') : '#app'); } renderWithQiankun({ bootstrap() {}, mount(props) { render(props); }, unmount() { app.unmount(); app = null; }, }); if (!qiankunWindow.__POWERED_BY_QIANKUN__) { render({}); }

用 qiankunWindow 而不是 window，是 vite-plugin-qiankun 提供的兼容封装。Vite 在 dev 模式下，直接操作 window 可能拿不到正确的沙箱上下文，用这个封装会更可靠。

3.3 生命周期改造中容易踩的细节坑

生命周期改造看起来简单，实际有几个细节不处理好就会出问题。

第一个是 axios 请求的 baseURL。JeecgBoot 的 axios 封装一般带了一个公共前缀，比如 /jeecg-boot/。这个前缀在独立运行时，通过 devServer 的 proxy 代理到后端服务。一旦接入 Qiankun，子应用请求的实际域名变成了主应用域名，所以主应用也要把 /jeecg-boot 这个前缀代理到 JeecgBoot 后端，否则登录、菜单、权限接口全部 404。

第二个是 render 函数里的 container。用 container.querySelector('#app') 挂载子应用时，要确保子应用 index.html 里真的有一个 id 为 app 的根节点。Qiankun 会把子应用的 HTML 整个拉回来放到容器里，如果根节点 id 对不上，挂载必然白屏。

第三个是全局事件和定时器清理。JeecgBoot 里可能注册了窗口监听事件、轮询定时器，如果 unmount 时不清理，子应用切换走以后事件依然存在，可能影响主应用，甚至造成内存泄漏。我习惯在 unmount 里把 instance 置空的同时，把全局监听也一并移除。

3.4 适配低代码生成页面的运行时问题

JeecgBoot 最有价值的部分，就是通过拖拉拽方式创建表单和页面。在独立运行模式下，低代码生成的页面是按需动态渲染的，靠的是后台返回的 schema 配置。但接入 Qiankun 后，我遇到一个比较特殊的情况：部分低代码页面依赖的组件，在子应用沙箱环境里没有被全局注册，运行时直接报“component is not registered”。

解决方式是在 main.js 里把低代码页面可能用到的组件统一全局注册，或者统一 import 一遍：

import OnlineForm from '@/components/OnlineForm'; Vue.component('OnlineForm', OnlineForm);

另外，低代码平台在运行时可能会动态向内联 style 标签。在沙箱开启后，这类动态插入的样式不一定能生效，会造成页面错乱。建议在主应用 start 时开启 experimentalStyleIsolation，并配合子应用端对基础组件样式做兼容处理。

4. 主应用注册与整体联调

4.1 子应用注册配置与路由映射

主应用把 JeecgBoot 注册成子应用后，有几个关键配置项需要和子应用严格对应，我列个表方便对照检查：

activeRule 建议设置成带前缀的路径，最好不要用 “/” 这种全匹配。否则用户访问主应用任何路径，都可能把子应用触发加载一遍，资源开销大，还容易出冲突。

如果你希望子应用只在特定菜单下被激活，可以用函数方式精确控制：

activeRule: (location) => { return location.pathname.startsWith('/jeecg'); }

4.2 登录态与权限的打通

这一节是很多接入方案里最头疼的部分。JeecgBoot 自带登录页和完整的用户权限体系，但在微前端架构下，如果用户已经在主应用登录过了，进入 JeecgBoot 子应用时还要再登录一次，体验非常割裂。

我建议的做法是：主应用通过 props 把 token 和用户信息传给子应用，子应用在 mount 时写入自己的存储，并初始化用户信息和菜单权限。

主应用注册子应用时传参：

registerMicroApps([ { name: 'jeecgboot', entry: '//localhost:3001', container: '#subapp-viewport', activeRule: '/jeecg', props: { token: getToken(), userInfo: getUserInfo(), }, } ]);

子应用 mount 时接收并使用：

export async function mount(props) { if (props && props.token) { localStorage.setItem('jeecg-token', props.token); store.commit('SET_TOKEN', props.token); } render(props); }

这里有一个实操细节值得注意：JeecgBoot 的菜单权限是需要向后端重新请求的，不是光有一个 token 就万事大吉。所以 mount 之后，最好主动调用一次获取用户信息和菜单权限的接口，让子应用的动态路由和菜单在每次进入时都刷新一遍。

export async function mount(props) { render(props); await store.dispatch('GetUserInfo'); await store.dispatch('UpdateMenu'); }

4.3 公共依赖与样式隔离处理

JeecgBoot 依赖 Vue、Vue Router、Ant Design Vue、Axios。理论上可以通过 externals 机制把公共依赖抽到主应用统一加载，减少子应用体积。但我实际测试下来，并不建议这样做。因为 JeecgBoot 的依赖版本可能和主应用不一致，强行外部化很容易导致组件 API 不兼容；低代码平台内部依赖关系复杂，外部化以后排查问题难度会明显增加。

我建议保持子应用独立打包，让 Qiankun 的沙箱机制来处理重复依赖。这样更省事，稳定性也更高。

样式隔离方面，建议开启 Qiankun 的 experimentalStyleIsolation，它会为子应用样式加作用域前缀，极大减少子应用样式污染主应用的概率。

start({ sandbox: { experimentalStyleIsolation: true, }, });

不过开启样式隔离后也要注意副作用。子应用里一些依赖 body 或全局选择器的弹层、提示组件，比如 Ant Design Vue 的 Modal、message、notification，可能会因为样式被隔离而显示异常。遇到这种情况，一般需要手动把这些弹层挂载到子应用容器下，或者单独为不受隔离的样式做处理。

4.4 静态资源路径处理

JeecgBoot 低代码平台里有很多上传的图片、文件、头像之类的资源。接入 Qiankun 后，这些资源的访问路径也需要处理。

我的做法是：资源地址统一用后端返回的绝对路径，不要用相对路径。如果必须用相对路径，就要保证子应用的 publicPath 与主应用路由前缀一致。之前遇到过一个典型问题：子应用入口 HTML 能加载，但引用的 JS、CSS 全部 404，最后发现就是 publicPath 写成了 /，资源跑到主应用域名根路径下去找了。把 publicPath 改成 /jeecg/ 后，问题立刻消失。

5. 接入过程中的典型问题与排查思路

5.1 子应用白屏：先分清是加载还是渲染问题

白屏是 Qinkun 接入里出现频率最高的问题，排查思路要有顺序，不然就是乱找。

第一步，打开浏览器 Network 面板，确认子应用 HTML 是否被成功加载。如果 HTML 都 404，检查主应用路由匹配和 entry 地址。

第二步，看子应用 JS 是否加载成功。如果 JS 404，大概率是 publicPath 配置错误或 jsonpFunction 冲突。

第三步，看控制台报错。如果报错是 “Cannot read properties of undefined”，多半是入口没有正确导出生命周期，或者沙箱环境里访问 window 出了问题。

第四步，切到 Elements 面板看 #subapp-viewport 里有没有内容。如果容器是空的，检查 render 函数里 container.querySelector('#app') 是否找得到节点。

我遇到过一种很隐蔽的情况：控制台一个错误都没有，但容器是空的，最后发现是子应用内部路由守卫被触发，跳到登录页了，而登录页因为资源路径问题又没渲染出来，看起来就是一片白。

5.2 路由跳转后子应用不渲染

另一个常见现象是：浏览器地址已经变成 /jeecg/xxx，但子应用始终没有加载出来或者一直在转圈。这种情况通常和 activeRule 匹配无关，而是子应用内部路由没匹配上。

一个常见原因是主应用和子应用都用了 history 路由。主应用地址切到 /jeecg/xxx 后，子应用内部路由的 base 没有同步，导致子应用认为当前路径不在它自己的路由表里，渲染了一个空页面。解决办法就是在子应用里改 hash 模式，或者给 history 模式传入和 activeRule 一致的 base。

还有一类情况是子应用路由守卫里做了登录校验，token 没拿到就强制跳登录页，导致展示空白。这时候需要把守卫里的 token 强校验逻辑做条件判断，或者确保 props 传 token 先于路由初始化完成。

5.3 API 请求跨域与代理问题

JeecgBoot 独立开发时，通过 devServer proxy 把 /jeecg-boot 代理到后端。接入 Qiankun 后，子应用资源加载和 API 请求都发生在主应用环境下，跨域问题就从子应用 devServer 转移到了主应用 devServer。

我本地联调时，在主应用 devServer 里额外加了一段代理：

proxy: { '/jeecg-boot': { target: 'http://localhost:8080', changeOrigin: true, }, }

子应用自己的 devServer 保留原有代理。这样独立调试和微前端联调都能正常工作。

如果部署到测试环境，主应用一般由 Nginx 承载，需要同时代理 /jeecg-boot 和 /jeecg 两个路径：

location /jeecg-boot/ { proxy_pass http://jeecg-backend:8080/; } location /jeecg/ { proxy_pass http://jeecg-frontend:3001/; }

这里的转发规则不是唯一的，要根据你自己的部署架构调整，但原则是：后端接口和子应用静态资源都要经过主应用域名能访问到。

5.4 登录失效和权限不同步

JeecgBoot 的 axios 响应拦截器里通常有一条逻辑：后端返回 401 就跳转到登录页。这个逻辑在微前端环境里非常容易引发问题。用户在子应用里停留时间长了，token 过期，后端返回 401，子应用马上跳自己的登录页，把用户从主应用框架里拽出去，体验很差。

我的处理方案是：在子应用的 401 处理里加一个判断，如果是被 Qinkun 加载的模式，就通过自定义事件通知主应用去处理登录失效；只有独立运行时，才跳子应用自己的登录页。

if (error.response.status === 401) { if (window.__POWERED_BY_QIANKUN__) { window.dispatchEvent(new CustomEvent('jeecg-unauthorized')); } else { router.push('/user/login'); } }

主应用监听这个事件，统一跳转主登录页。这样既保持了单点登录体验，又不会让子应用的登录页把用户带走。

5.5 一个容易被忽略的沙箱常见问题

Qiankun 的沙箱机制会拦截子应用里 window.addEventListener 的注册，为的是在应用卸载时自动清理。但 JeecgBoot 有些功能，比如 WebSocket 连接、全局键盘事件、消息推送，正是通过 window.addEventListener 实现的。在沙箱开启的情况下，这些全局事件可能被代理到虚拟 window 上，导致主应用拿不到，或者切换路由后事件被清除。

遇到这种情况，建议把关键事件绑定改到具体的 DOM 节点上，或者由主应用统一管理这类全局消息，子应用通过 props 接收通知。这样虽然改起来多花点时间，但从架构上看更干净。

6. 一些实操后的个人建议

JeecgBoot 接入 Qiankun，技术上并不复杂，难的是细节多：路由模式、公共路径、代理转发、登录态联动、低代码组件注册、样式隔离，每一个环节都可能出问题。我做完整个项目之后的体会是：先让子应用独立跑得明明白白，再动微前端改造，是最稳的路径。

另外想说一句，微前端不是银弹。样式隔离、沙箱隔离、路由隔离都有成本和边界。比如我开启 experimentalStyleIsolation 之后，JeecgBoot 的部分弹层样式确实出了问题，最后只能用“把影响范围限制在子应用页面内部 + 手动修复关键样式”的方式解决。这个过程里没有能抄一次的作业，必须有耐心一个个踩、一个个修。如果你也正在走这条路，不妨从一个最小的可运行 demo 开始，先把空页面子应用跑通，再逐步把 JeecgBoot 的功能引进来。增量式接入，会比一把梭省心很多。