qiankun微前端实践 | 源码解析

我见过很多项目用qiankun微前端实践，但真正稳定落地的并不多。关键不在于框架选得对不对，而在于怎么配置主应用和子应用、怎么处理资源加载、怎么保证子应用生命周期可控。比如主应用用webpack打包，子应用用vite，两者需要统一模块解析方式，否则容易出现模块路径错误。子应用生命周期钩子必须严格按规范写，否则主应用会卡死。我之前踩过的一个坑是，子应用默认暴露了window对象，导致主应用无法预加载，得手动设置子应用的入口函数，把window对象隔离。还有就是子应用打包后的静态资源地址要绝对路径，否则会代理到主应用的路径上，出错。在线上部署时，子应用的publicPath要根据环境动态调整，否则静态资源加载失败。microApp的加载方式直接影响性能，必须用dynamicImport。主应用在registerMicroApps前要配置qiankun的全局变量，否则子应用找不到主应用的上下文。子应用的entry要指定main和vue文件，不能只写html。我在实际项目中发现，子应用如果使用了第三方库，需要配置externals，防止重复打包。主应用和子应用的manifest.json文件要有统一的格式，否则注册不上。子应用的生命周期钩子不能有异步操作，否则会触发多次加载。主应用需要配置qiankun的全局钩子，比如beforeLoad、beforeMount，用来控制加载时机。子应用如果使用了history模式，要配置hashHistory，否则路由跳转会出问题。主应用的容器元素需要设置id，否则子应用无法挂载。子应用如果要访问主应用的全局变量，要用qiankun的window方法。主应用的打包工具要配置publicPath为相对路径，以便子应用能正确加载资源。在线上部署时，主应用和子应用的域名要统一，否则会跨域。子应用的manifest.json文件中，entry字段要写完整路径，不能写相对路径。主应用要配置qiankun的sandbox模式，防止子应用污染全局变量。子应用的路由要独立配置，不能和主应用混在一起。子应用如果使用了Vue Router，要配置base参数，否则路径会出错。主应用和子应用的版本控制要统一，避免兼容性问题。子应用的样式要使用scoped或者shadow DOM，否则会覆盖主应用的样式。主应用在加载子应用时，要使用qiankun的loadMicroApp方法，而不是直接挂载。子应用的主文件要导出一个函数，返回一个Promise，才能被qiankun正确加载。主应用的容器元素要设置样式，防止子应用布局错乱。


▌ 技术参考

一 技术背景与核心概念
qiankun是基于single-spa的微前端方案，依赖于模块化和动态加载。主应用负责注册子应用并管理其生命周期，子应用则需要具备独立运行的能力。qiankun的核心在于通过动态脚本加载实现子应用的插件式引入。在2024-2026年的项目中，越来越多团队采用了这种架构，尤其在大型单体应用拆分时，qiankun提供了较成熟的解决方案。主应用通常使用React、Vue或Angular，子应用可以是独立的项目，甚至基于不同框架。关键点在于主应用和子应用的通信机制、资源加载方式、样式隔离策略。子应用的入口文件必须导出一个函数，返回一个Promise，格式是：export default function() { return Promise.resolve() }，否则无法被qiankun识别。


二 具体操作方法或配置步骤
主应用需要使用qiankun的registerMicroApps函数注册子应用，配置项包括entry、container、name、activeRule等。entry是子应用的入口地址，通常是打包后的index.html，或通过script标签动态加载。container是挂载子应用的DOM节点，需要提前在主应用中创建。name是子应用的唯一标识，必须对应子应用暴露的全局变量。activeRule是子应用活跃的条件，通常基于URL匹配。例如：registerMicroApps([ { entry: '//sub-app-1.com', container: '#subapp-container', name: 'sub1', activeRule: '/sub1' } ])。子应用需要在入口文件中添加qiankun的声明，例如：window.qiankun = { bootstrap: () => {}, mount: () => {}, unmount: () => {} }。主应用在启动qiankun前，要确保容器元素已经挂载到DOM。子应用的打包配置要设置publicPath为相对路径，比如'./'，避免加载异常。


三 常见踩坑场景与避坑方案
子应用如果使用了history模式，主应用的路由配置可能无法正确拦截。这时候要使用qiankun的hashHistory替代，或者在子应用的入口函数中设置history对象的base属性。主应用在加载子应用时，如果容器元素没有正确设置，子应用会报找不到挂载点的错误。需要确保容器id在DOM中存在，并且在qiankun初始化前就已加载。子应用使用了第三方库，如果未正确配置externals，可能导致重复打包，从而增加体积。可以在子应用的vite或webpack配置中设置externals字段，将依赖项排除。主应用在注册子应用时，如果activeRule配置错误，子应用永远不会被激活。需要确保activeRule是基于URL的正则表达式，或者使用通配符。子应用如果在初始化阶段执行了全局sideEffect，可能会影响主应用。要在子应用的bootstrap函数中限制执行范围，或者使用sandbox模式隔离。主应用的子应用配置要写死在代码中，否则无法动态加载。可以使用环境变量或配置文件管理子应用列表。


四 性能影响或效率对比
qiankun的微前端方案在加载子应用时，需要通过动态脚本加载，这会增加首次加载的延迟。与传统的单体架构相比，微前端在资源加载和页面切换时会带来额外的性能开销。不过，在2024-2026年的实践中，通过优化子应用的打包方式、使用预加载策略、调整activeRule的匹配规则，可以有效缓解这个问题。例如，使用vite的按需加载特性，可以减少子应用首次启动的体积。主应用如果频繁触发子应用的卸载和加载，会增加内存和CPU的负担，影响整体性能。建议在子应用加载完成后，通过qiankun的registerMicroApps函数进行优化，减少不必要的重复加载。子应用的预加载策略需要配置，比如使用qiankun的loadMicroApp方法提前加载。主应用的打包工具应配置splitChunks，将子应用的依赖拆分出来，避免污染全局依赖。在实际测试中，qiankun的加载效率比传统单页应用高，但比纯静态页面低。需要根据项目需求权衡选择。


五 适用场景与局限性
qiankun适合用于大型单体应用的拆分，尤其在需要保持主应用的稳定性，同时允许子应用独立开发和部署时。例如，后台管理系统中，主应用负责菜单和权限控制，子应用负责具体功能模块。优点在于子应用可以独立维护、更新，主应用不需要重新打包。但局限性也很明显，比如子应用之间共享状态困难，样式隔离不彻底，全局变量污染问题依然存在。此外，qiankun对子应用的依赖管理不够完善，容易出现版本不一致的问题。动态加载子应用的过程可能会导致页面闪烁，需要优化子应用的资源加载策略。在某些场景下，比如子应用需要复杂的初始化逻辑，qiankun的生命周期钩子可能不够灵活。需要结合其他技术手段，如自定义钩子或封装加载层，来提升体验。


六 替代方案或进阶技巧
如果项目对性能要求极高，可以考虑使用iframe方案替代qiankun，但会牺牲部分功能，比如样式隔离和全局变量通信。另一种替代方案是使用single-spa框架，它更加底层，但需要自己处理更多细节，比如生命周期管理、状态同步。在实际项目中，qiankun的sandbox模式可以有效隔离子应用的全局变量，但需要配置额外的参数，比如将子应用的dom元素包裹在sandbox标签中。同时，可以使用qiankun的props配置项，让主应用向子应用传递参数，比如菜单项、用户信息等。子应用如果需要进行通信，可以使用postMessage方法，或者通过qiankun暴露的window对象进行访问。在子应用内部，可以通过qiankun的window方法获取主应用的全局变量，比如window['mainApp']。主应用可以使用qiankun的getMicroApp方法获取子应用实例，进行更细粒度的控制。另外，子应用可以通过qiankun的onError事件捕获加载异常，避免页面崩溃。对于复杂项目，建议将子应用封装成独立的npm包，通过引入方式进行管理，而不是直接引用。这样更便于版本控制和依赖管理。


七 子应用打包配置
子应用的打包配置是微前端实践的关键，需要确保打包后的静态资源路径正确，并且不污染全局变量。以vite为例，子应用的打包配置应包括output.publicPath设置为'./'，这样子应用的资源会加载到当前路径下，而不是主应用的根路径。同时，子应用的manifest.json文件需要配置entry为完整的入口地址，例如'./index.html'。如果子应用是Vue项目，需要在入口文件中添加qiankun的声明，确保生命周期钩子正确触发。打包时，可以使用--modern参数，以现代模式打包，提升兼容性。子应用的依赖项如果不需要打包，可以在vite配置的externals字段中声明，避免重复打包。对于React项目，同样需要配置webpack的externals选项，确保子应用的依赖项正确引用。打包后的子应用需要放在独立的服务器或静态文件目录中，避免主应用的代理配置出错。子应用的打包结果应包含main.js、vue.js、manifest.json等关键文件，确保能被qiankun正确加载。


八 主应用容器配置
主应用的容器配置决定了子应用的挂载位置和样式隔离效果。容器元素的id必须在主应用的HTML中存在，并且位置要合适，比如放在body底部。容器元素的样式需要设置为position: absolute，这样子应用的布局不会影响主应用。如果子应用的样式未隔离，可能会覆盖主应用的样式，导致视觉混乱。通过配置qiankun的样式隔离参数，比如使用shadow DOM，可以避免这种情况。主应用可以使用CSS变量来控制子应用的样式，确保子应用能够独立调整。容器元素的初始状态应为隐藏，直到子应用加载完成后再显示。如果容器元素被频繁替换，可能会导致页面布局抖动，影响用户体验。主应用可以使用qiankun的loadMicroApp方法配合加载状态，控制容器的显示隐藏。容器元素的host属性可以设置为'none'，避免被浏览器解析成iframe。


九 子应用生命周期钩子
子应用的生命周期钩子必须严格遵循qiankun的规范，否则会导致加载失败或页面卡死。bootstrap函数是子应用启动前的初始化阶段，需要在这个阶段完成依赖注入和资源准备。mount函数是子应用挂载到容器的阶段，必须在这个函数中执行DOM操作和挂载应用。unmount函数是子应用卸载时的清理阶段，确保资源被释放。如果子应用在这些钩子中执行了异步操作，可能会导致钩子多次触发，进而引发问题。例如，bootstrap函数中如果调用了async函数获取数据，可能会导致子应用无法正常启动。可以使用Promise来确保初始化完成后再执行后续操作。子应用的钩子函数需要导出为一个对象，包含bootstrap、mount、unmount三个方法。每个方法都需要返回一个Promise，确保qiankun能正确识别。如果子应用的钩子函数没有正确返回，qiankun可能会认为子应用加载失败。


十 主应用路由拦截与子应用激活
主应用的路由拦截是微前端实践的重要环节，需要确保子应用在正确时机被激活。qiankun提供了activeRule参数，用于匹配子应用的激活条件。例如，设置activeRule为'/sub1'，当URL匹配该路径时，子应用会被加载。需要确保activeRule的正则表达式写法正确，否则可能无法正确匹配。主应用的路由可以在qiankun的beforeMount钩子中进行拦截，根据URL动态加载子应用。如果子应用的激活规则与主应用的路由冲突，会导致页面加载异常。可以通过路由守卫结合qiankun的activeRule参数，实现更精确的控制。在实际项目中，主应用的路由配置可能需要调整，比如将子应用的路径排除，避免重复加载。如果子应用需要动态加载，可以使用qiankun的loadMicroApp方法，根据条件动态注册。在某些场景下，主应用的路由配置需要与子应用的路由配置解耦，确保子应用能独立运行。


十一 子应用打包工具选择与配置
子应用的打包工具选择直接影响微前端的运行效率和稳定性。以vite为例，配置output.publicPath为'./'，确保子应用的资源路径正确。子应用的manifest.json文件需要配置entry为完整路径，比如'./index.html'。如果子应用是Vue项目，可以配置vite的rollupOptions，将子应用的依赖项按需加载，减少包体积。对于React项目，同样需要配置webpack的externals，确保子应用的依赖项正确引用。打包工具的配置应确保子应用的静态资源不被主应用的打包过程污染，否则会导致加载异常。子应用的打包结果应包含main.js、vue.js、manifest.json等关键文件，确保能被qiankun正确加载。在2024-2026年的实践中，vite由于其性能优势，成为很多项目的首选。但需要注意vite的打包方式与qiankun的加载机制兼容性，避免出现资源加载失败的情况。


十二 主应用与子应用通信方案
主应用与子应用之间的通信是微前端实践的核心难点之一。常见的通信方式包括postMessage、window对象挂载以及自定义事件。比如，主应用可以通过window['subApp']向子应用传递参数，或者调用子应用暴露的函数。子应用同样可以通过window['mainApp']访问主应用的全局变量。在实际项目中，建议使用qiankun提供的props参数进行通信，这样可以避免直接操作window对象带来的风险。props参数可以传递菜单项、用户信息等全局状态，确保子应用能正确获取数据。需要注意的是，props参数需要在子应用的mount函数中接收，否则无法使用。如果子应用需要频繁获取主应用的数据，可以通过自定义事件进行监听，比如使用window.addEventListener('message', function)。这种方法在复杂的项目中更为可靠，但会增加通信的复杂度。此外，可以使用全局状态管理工具，比如Vuex或Redux，但需要确保主应用和子应用的状态同步。


十三 子应用样式隔离策略
子应用的样式隔离是微前端实践中容易被忽视却又至关重要的部分。如果不进行隔离，子应用的样式会覆盖主应用的样式，导致页面布局混乱。qiankun提供了两种样式隔离方式：sandbox和shadow DOM。sandbox模式会将子应用的DOM元素包裹在允许的沙箱中，防止样式污染。shadow DOM则通过创建独立的文档片段，实现更彻底的隔离。在实际项目中，建议优先使用sandbox模式，因为它对开发者更友好，且兼容性更好。如果子应用的CSS文件未正确打包，或者未使用scoped样式，可能会导致样式混乱。可以通过子应用的打包配置，强制使用scoped样式或shadow DOM，确保样式隔离。主应用的CSS文件需要使用CSS变量，这样子应用可以独立调整样式，而不会影响主应用。如果子应用的样式需要与主应用部分融合，可以通过CSS层叠规则，设置子应用的样式优先级低于主应用，避免冲突。


十四 子应用资源加载与预加载
子应用的资源加载方式直接影响整体性能，尤其是在首次加载时。qiankun的loadMicroApp方法支持预加载，可以在主应用初始化时提前加载子应用的资源，减少首次访问的延迟。预加载需要在主应用的路由守卫中实现，例如在进入某个页面前，先调用loadMicroApp加载子应用的资源。资源加载失败时，qiankun会自动重试，但需要配置超时时间，例如设置loadOptions的timeout为5000。子应用的资源加载应尽可能使用按需加载，减少不必要的网络请求。例如，在子应用的入口文件中，使用import动态加载核心模块，而不是一次性打包所有代码。资源加载的优化还可以通过缓存策略实现，比如在子应用打包时设置cache-Control头，提升资源复用率。如果子应用的资源加载过慢，会影响用户体验，需要合理配置资源加载策略，确保加载效率。


十五 子应用版本管理与依赖控制
子应用的版本管理是微前端实践中的关键点，直接影响主应用的兼容性和稳定性。在2024-2026年的项目中，很多团队使用npm包管理子应用，这样可以更方便地进行版本控制。比如，将子应用发布到私有npm仓库，主应用通过import语句引入，确保版本一致性。子应用的依赖项如果未正确管理，可能会导致版本冲突。可以通过配置子应用的externals字段，排除不需要打包的依赖项。比如，在vite配置中设置externals: [ ['vue', 'Vue'] ]，确保vue库不被重复打包。主应用需要定期更新子应用的版本，确保兼容性。如果子应用的版本更新后出现兼容性问题，可以通过qiankun的loadMicroApp方法进行回滚。子应用的版本信息应该在manifest.json文件中体现，主应用在注册子应用时需要根据版本号动态加载。在实际项目中，建议使用版本号控制，避免因依赖变化导致的不可预期问题。