《Qiankun》微前端快速上手:5步集成多应用

Qiankun 是由 UmiJS 团队推出的开源微前端解决方案，旨在帮助开发者在同一个页面中集成多个独立开发、部署的前端子应用。它支持主流框架（如 React、Vue、Angular）无缝接入，适用于大型企业级项目中模块解耦与团队协作场景。学习 Qiankun 的基本使用方法，有助于提升前端架构的灵活性和可维护性。

前期准备与环境搭建

1. 确保本地已安装 Node.js（建议版本 12 及以上）和 npm 或 yarn 包管理工具。 验证命令:`node -v` 和 `npm -v`，输出版本号即表示安装成功。
2. 创建主应用（基座应用）项目目录并初始化: ```bash mkdir main-app && cd main-app npm init -y ```
3. 安装 Qiankun 核心依赖: ```bash npm install qiankun ```
4. 创建入口文件 `index.html` 和 `main.js`，用于注册和加载子应用。 此时项目结构具备运行基础，Qiankun 已可被引入至主应用中。

核心功能操作步骤

1. 在主应用 `main.js` 中注册子应用: 使用 `registerMicroApps` 方法配置子应用信息，包括名称、入口地址、挂载容器等: ```js import { registerMicroApps, start } from 'qiankun'; registerMicroApps([ { name: 'vue-app', entry: '//localhost:8080', container: 'subapp-container', activeRule: '/vue', }, ]); ```
2. 调用 `start()` 启动微前端应用: ```js start(); ``` 此时主应用将监听路由变化，并按规则动态加载对应子应用。
3. 创建子应用（以 Vue 为例），在其 `public/index.html` 中添加 `window.__POWERED_BY_QIANKUN__` 判断逻辑，避免样式冲突。
4. 子应用需修改打包配置，使其支持跨域加载与动态导出: - 设置 `output.library` 为全局变量名 - 启用 `devServer.headers['Access-Control-Allow-Origin'] = ''`
5. 启动主应用和子应用服务，访问主应用页面并导航至 `/vue` 路径，子应用将在指定容器中渲染成功。

实用技巧与注意事项

- 子应用应避免直接操作 `document` 或设置全局样式，防止影响主应用或其他子应用。 - 推荐使用 `import-html-entry` 解析 HTML 入口文件，Qiankun 内部已集成该机制。 - 主应用可通过 `initGlobalState` 实现子应用间通信，传递自定义事件和数据。 - 子应用生命周期函数（bootstrap、mount、unmount）必须正确导出，否则无法正常挂载。 - 生产环境中，建议通过 CDN 托管子应用资源，提升加载效率。

常见问题解决

1. 子应用无法加载:检查子应用是否开启 CORS 支持，确保开发服务器返回 `Access-Control-Allow-Origin` 头。
2. 样式隔离失效:确认主应用未强制共享 CSS，或启用沙箱模式（Sandbox）增强隔离。
3. 路由冲突:子应用应使用浏览器 History 模式，并配合主应用的 `activeRule` 规则设置前缀路径。
4. 重复加载资源:通过 Webpack 的 `externals` 配置提取公共依赖，减少冗余请求。
5. 生产部署失败:确保子应用构建后资源路径为相对路径或完整 URL，避免 404 错误。 掌握 Qiankun 的集成流程后，可逐步扩展多团队协同开发的复杂前端系统。