qiankun架构设计：从入门到精通

▌ 技术引导
qiankun架构设计不是简单的iframe嵌套，而是通过子应用沙箱机制实现微前端的动态加载与资源隔离。我见过很多团队在使用qiankun时陷入局部应用资源冲突、主应用全局状态污染、样式覆盖等问题，直接导致页面加载卡顿甚至白屏。真实场景中，必须配置主应用的子应用注册路径、加载策略、生命周期钩子，同时避免使用window对象直接操作子应用状态。例如，使用qiankun的registerMicroApps时，必须指定entry、activeRule、container、props等参数，且props需要确保子应用能正确获取主应用上下文。我踩过的坑包括子应用挂载后无法响应路由变化、子应用与主应用共享的全局变量被重复初始化、子应用初始化时出现重复挂载问题。解决方式是使用qiankun的sandbox沙箱策略，结合动态挂载、生命周期控制、资源隔离机制，才能让微前端真正稳定运行。

▌ 技术参考

一 项目初始化与依赖管理
qiankun的初始化需要在主应用中引入qiankun模块，并使用registerMicroApps注册子应用。实际操作中，主应用需要引入qiankun库：npm install qiankun --save。配置时需确保子应用的入口地址、activeRule、container等参数正确。例如，注册一个子应用时，配置如下：
const apps = [
{
name: 'subApp1',
entry: '//localhost:7101',
activeRule: '/sub1',
container: document.getElementById('subapp-container'),
props: { user: 'admin' }
}
];
registerMicroApps(apps, { beforeLoad: (app) => console.log('before load', app.name) }, () => { console.log('所有子应用加载完成') });
在子应用中需要使用qiankun的bootstrap、mount、unmount钩子，确保应用在沙箱环境下正确加载。


二 沙箱与加载策略配置
qiankun的沙箱机制是关键，它通过创建虚拟的window对象来隔离子应用的全局变量和DOM操作。配置时需要在registerMicroApps中指定sandbox参数，例如：
registerMicroApps(apps, {
sandbox: {
experimentalStyleIsolation: true,
alignZIndex: true,
strategy: 'window'
},
beforeLoad: (app) => console.log('before load', app.name)
});
其中，experimentalStyleIsolation控制样式隔离，alignZIndex确保子应用z-index不冲突，strategy指定沙箱类型。如果子应用内有全局变量污染主应用，必须开启strategy为'window'，否则使用'hash'或'umd'策略可能导致状态混乱。



三 路由冲突与activeRule设置
子应用的activeRule必须精准匹配，否则可能引发路由冲突。常见错误是设置activeRule为'/'，导致所有子应用同时加载。正确的做法是为每个子应用分配独立的路由前缀，如：
activeRule: '/sub1'
activeRule: '/sub2'
如果主应用使用react-router，需要确保子应用的路由不与主应用重叠。或者使用qiankun的loadMicroApp方法动态加载子应用。同时，避免在子应用中使用window.location.hash，因为可能会干扰主应用的路由跳转。



四 子应用生命周期钩子
子应用需要实现bootstrap、mount、unmount三个生命周期钩子。例如，子应用的入口文件中需要定义：
export async function bootstrap({ loading }) {
console.log('子应用bootstrap');
loading(false);
}
export async function mount(props) {
console.log('子应用mount', props);
// 将props挂载到子应用的全局变量中
window.subAppProps = props;
}
export async function unmount() {
console.log('子应用unmount');
// 清理子应用的全局变量
window.subAppProps = null;
}
如果不正确实现这些钩子，可能导致子应用在卸载后仍占用内存资源，甚至触发重复挂载。特别注意，在mount中必须将props注入到子应用的全局变量中，否则子应用无法获取主应用的上下文。



五 资源隔离与样式覆盖
样式覆盖是qiankun最常见的坑。如果不开启实验性样式隔离，子应用的CSS可能会污染主应用。解决方案是配置experimentalStyleIsolation为true，并在子应用中使用scoped CSS。例如，在子应用的vue组件中，使用scoped属性，或者在React组件中使用CSS Modules。同时，可以使用qiankun的样式隔离配置项，如：
sandbox: {
experimentalStyleIsolation: true,
styleIsolation: 'isolated'
}
如果子应用使用less或sass，需要确保变量作用域不被主应用覆盖。



六 静态资源加载与性能优化
qiankun的子应用加载时，默认会使用动态加载策略，但实际中很多团队会误用静态资源包，导致首次加载慢。正确做法是使用动态加载方式，结合webpack的splitChunks和code splitting技术。例如，在子应用的入口文件中配置：
import('./index').then((mod) => mod.default);
同时，主应用应使用懒加载策略，避免一次性加载所有子应用。性能优化还包括使用预加载、资源缓存、代码分割，以及qiankun的loading参数控制加载状态。



七 主应用与子应用通信
子应用与主应用通信需通过qiankun的setGlobalState和getGlobalState方法。例如，在主应用中：
import { setGlobalState } from 'qiankun';
setGlobalState({ user: 'user123' }, 'subApp1');
在子应用中：
import { getGlobalState } from 'qiankun';
const user = getGlobalState('user');
但必须注意，通信时要严格绑定子应用名称，否则数据会被错误注入。此外，可以使用事件总线或自定义协议进行跨应用通信，但需确保子应用能正确监听主应用的postMessage或其他事件。



八 子应用挂载异常与调试技巧
子应用挂载失败常见的错误是子应用入口地址错误、跨域未配置或子应用未正确声明qiankun入口。调试时，可以使用qiankun的log输出详细信息，或者在子应用中添加console.log监听挂载过程。例如，在主应用中添加：
registerMicroApps(apps, {
beforeLoad: (app) => console.log('before load', app.name),
beforeMount: (app) => console.log('before mount', app.name),
beforeUnmount: (app) => console.log('before unmount', app.name)
});
还可以在子应用的入口文件中添加错误处理逻辑，如：
window.qiankun = window.qiankun || {};
window.qiankun.__onloading = function (err) {
console.error('子应用加载失败', err);
};


九 子应用与主应用共享状态管理
qiankun支持主应用和子应用共享状态，但需要通过qiankun的全局状态管理接口。例如，主应用可以将用户状态通过getGlobalState传递给子应用，子应用也可以通过setGlobalState修改状态。但需要注意，状态共享应通过接口传递，而非全局变量。此外，可结合Redux或Vuex进行状态管理，确保子应用能正确获取和更新状态。



十 子应用动态加载与卸载
动态加载子应用可以通过loadMicroApp方法实现，例如：
loadMicroApp({
name: 'subApp1',
entry: '//localhost:7101',
container: document.getElementById('subapp-container'),
props: { user: 'admin' },
sandbox: { strategy: 'window' }
});
动态卸载时，需调用unmountMicroApp方法，并传入子应用名称。注意，在卸载时要确保子应用已经完成渲染，否则可能引发内存泄漏或DOM操作错误。此外，可以在主应用中监听子应用卸载事件，如：
onError: (error) => {
console.error('子应用卸载失败', error);
}



十一 子应用资源冲突与隔离
子应用的资源冲突主要发生在全局变量、事件监听、DOM操作等方面。例如，如果主应用和子应用都注册了相同的全局变量，可能导致数据覆盖。解决方案是使用qiankun的沙箱机制，并在子应用中使用相对路径引入资源，避免绝对路径。此外，可以在子应用中使用process.env.NODE_ENV判断是否为生产环境，避免在开发环境引入冗余资源。



十二 子应用与主应用导航同步
子应用与主应用的导航同步是关键，否则可能出现路由不匹配或页面错误。可以通过qiankun的globalState传入当前路由信息，或者使用location.hash同步导航。例如，在主应用中监听路由变化：
router.beforeEach((to, from, next) => {
setGlobalState({ currentRoute: to.fullPath }, 'subApp1');
next();
});
在子应用中监听全局状态变化：
import { getGlobalState, onGlobalStateChange } from 'qiankun';
onGlobalStateChange((state, prev) => {
console.log('路由变化', state.currentRoute);
// 根据路由变化更新子应用内部状态
}, false);



十三 子应用初始化失败与回退机制
子应用初始化失败可能是因为网络问题、入口地址错误、依赖未加载等。需要在registerMicroApps中配置error处理函数，例如：
registerMicroApps(apps, {
error: (err) => {
console.error('子应用初始化失败', err);
// 可在此处添加回退机制，如重试加载、显示错误页面
}
});
同时，在子应用中可以使用try-catch块捕获初始化错误，并通过window.qiankun.__onloading接口通知主应用。



十四 子应用与主应用样式兼容性
子应用的样式兼容性问题通常出现在字体、颜色、布局等层面。建议在子应用中使用CSS-in-JS方案，或者在构建时添加样式隔离配置。例如，在webpack中配置scoped CSS：
module.exports = {
css: {
modules: true,
localIdentName: '[local]___[hash:base64:5]'
}
};
同时，可以在主应用中设置全局样式，但需确保子应用的样式优先级低于主应用，避免覆盖。



十五 子应用与主应用版本兼容性
qiankun版本迭代频繁，子应用与主应用版本不一致可能导致兼容性问题。例如，主应用使用qiankun 3.0，而子应用使用qiankun 2.0，可能引发hook失效或配置错误。解决方式是确保主应用和子应用使用相同版本的qiankun，并在构建时使用兼容性策略，如：
import { registerMicroApps, start } from 'qiankun';
registerMicroApps([
{
name: 'subApp1',
entry: '//localhost:7101',
activeRule: '/sub1',
container: document.getElementById('subapp-container')
}
], {}, () => {
start();
});
同时，在子应用的入口文件中，确保使用正确的qiankun模块引用和钩子函数定义。