5分钟上手umi-plugin-qiankun：Umi+qiankun微前端快速入门实战教程

5分钟上手umi-plugin-qiankun：Umi+qiankun微前端快速入门实战教程

【免费下载链接】umi-plugin-qiankunUmi plugin for qiankun.项目地址: https://gitcode.com/gh_mirrors/umi/umi-plugin-qiankun

umi-plugin-qiankun（npm 包名@umijs/plugin-qiankun）是 Umi 官方为 qiankun 打造的微前端插件，帮你用极少配置就把「一个主应用 + N 个子应用」的架构搭起来。无需手写复杂的 qiankun 初始化代码，装插件、改两行配置，主应用和子应用就能互相注册、加载、通讯，并支持 JS 沙箱与预加载。本文带你 5 分钟跑通一套完整的 Umi 微前端 Demo。

上图演示效果：顶部导航由主应用提供，点击 app1 / app2 时，对应子应用被动态加载进主应用容器——这就是 qiankun 微前端的典型体验。

🎯 这个插件能做什么

• 基于 qiankun：成熟可靠的微前端方案，jsSandbox开启后子应用 JS 互不污染
• 主子应用都用 Umi：一份技术栈开发所有应用，团队上手零成本
• 兼容多种路由模式：主子应用均支持 browser、hash 等 history 模式
• 父子应用通讯：props 传值 + Hooks 共享数据两种玩法
• 子应用生命周期可自定义：bootstrap()、mount()、unmount()随意扩展
• 主子应用本地联调：各自umi dev起服务即可联调，不用部署

插件核心代码分布在 src/master/（主应用侧：注册子应用、生成路由）和 src/slave/（子应用侧：导出生命周期），逻辑非常精简，值得通读一遍。

📦 一键安装：最快配置方法

在主应用和每个子应用中都要安装插件：

$ npm i @umijs/plugin-qiankun -S # 或 yarn add @umijs/plugin-qiankun

主应用在.umirc.js中加入一行插件配置：

export default { plugins: [ ['@umijs/plugin-qiankun', { master: { /* 子应用注册信息，见下文 */ } }], ], };

子应用配置更简单，插件名后不加参数即可：

export default { base: '/app1', // 子应用路由前缀，默认取 package.json 的 name plugins: ['@umijs/plugin-qiankun'], };

就这两步，框架层面的接入已完成 ✅

🧭 主应用：如何注册子应用

在主应用的master.apps里声明每个子应用的name（唯一 id）、entry（地址）和base（路由前缀）：

master: { apps: [ { name: 'app1', entry: '//localhost:7001', base: '/app1' }, { name: 'app2', entry: '//localhost:7002', base: '/app2' }, ], jsSandbox: true, // 开启 JS 沙箱，避免全局变量污染 prefetch: true, // 预加载子应用，切换更流畅 }

常用主应用配置一览：

💡 除了「构建期写死」，还支持运行时动态注册：在主应用src/app.js中export const qiankun = fetch('/config').then(...)，从后端接口拉取子应用列表，实现微前端动态化。参考示例 examples/master/app.js。

⚠️ 运行时方式下插件不会自动生成子应用路由，需要在pages/下建一个空容器页并配置对应路由，否则会 404。

🚀 子应用：接入三步走

1. 设置base：与主应用注册时的base保持一致（如/app1）
2. 配置插件：plugins: ['@umijs/plugin-qiankun']
3. （可选）自定义生命周期：在子应用src/app.js导出qiankun对象：

export const qiankun = { bootstrap(props) { console.log('加载之前', props); }, mount(props) { console.log('渲染之前', props); }, unmount(props) { console.log('卸载之后', props); }, };

生命周期钩子里能拿到主应用通过props下发的任意数据，是通讯的入口。子应用侧生命周期实现可查看 src/slave/lifecycles.ts。

🔧 本地联调小技巧：建议在子应用用.env固定端口（如PORT=8081），保证主应用entry配置稳定，参考 examples/app1/serve.json 的开发服务配置。

🤝 父子应用如何通讯

插件内置两种方案，按需选择：

方案一：基于 props 传递—— 类似 React 组件传参。主应用注册子应用时挂上props，子应用在生命周期钩子里接收，适合传函数、配置等。

方案二：基于 Hooks 共享数据—— 适合跨应用共享状态：

1. 主应用在src/rootExports.js中导出数据与操作函数，示例见 examples/master/rootExports.js
2. 子应用用import { useRootExports } from 'umi'一行拿到，用法参考 examples/app1/pages/index.js

const rootExports = useRootExports(); // 直接读写主应用导出的共享数据

⚠️ Hooks 方案需保证主子应用共享同一份 React 实例（强制 external React），且只能在函数组件中使用。

❓ 新手高频避坑指南

• history 模式保持一致：主子应用都用 browser 或都用 hash，插件会自动补空路由避免 404；模式不一致需自行处理路由
• base三处要一致：主应用注册、子应用.umirc.js的base、子应用 URL 前缀
• 挂载容器 id：子应用默认挂载到#root-subapp，若自定义了mountElementId，注意主、子应用容器 id 不要相同
• 版本要求：插件适配 Umi@2（umi >= 2.12.0）与 React 16；如果你用的是 Umi@3，请改用 Umi 插件库中对应的 qiankun 插件，版本不通用

📂 示例代码去哪看

仓库内自带一套完整可运行的主子应用 Demo，强烈建议 clone 下来直接跑：

在根目录执行yarn && yarn build && yarn start即可同时启动主应用和全部子应用，打开浏览器就能看到开头的 Demo 效果 🎉

小结：umi-plugin-qiankun 的价值在于「约定大于配置」——安装插件、写好base和apps，qiankun 的沙箱、预加载、生命周期、路由接管全部自动搞定。剩下的精力，就该花在业务本身了。

【免费下载链接】umi-plugin-qiankunUmi plugin for qiankun.项目地址: https://gitcode.com/gh_mirrors/umi/umi-plugin-qiankun