微前端架构的核心思想是将一个庞大的前端应用拆分成多个独立开发、独立部署、独立运行的子应用，主应用负责整体框架的调度和子应用的加载，子应用专注于自身业务功能的实现，这种模式非常适合大型团队的多人协作场景。
微前端架构选型
目前主流的JavaScript微前端方案有single_spa、qiankun、webpack模块联邦等，不同方案的特点如下：
| 方案名称 | 核心特点 | 适用场景 |
|---|---|---|
| single_spa | 轻量，提供基础的子应用加载和生命周期管理 | 对定制化要求高的项目 |
| qiankun | 基于single_spa封装，内置沙箱、资源加载、通信等能力 | 快速落地微前端的中大型项目 |
| webpack模块联邦 | 基于webpack5，实现模块级别的共享和加载 | 同构webpack生态的项目 |
基于qiankun构建微前端应用
qiankun是目前落地成本较低的微前端方案，下面以qiankun为例讲解完整的构建流程。
1. 主应用搭建
主应用负责注册子应用、控制子应用的加载和卸载，首先初始化一个基础的JavaScript项目，安装qiankun依赖：
# 初始化项目 npm init -y # 安装qiankun npm install qiankun --save
主应用的核心逻辑是注册子应用，代码如下：
import { registerMicroApps, start } from 'qiankun';
// 注册子应用
registerMicroApps([
{
name: 'sub-app-1', // 子应用名称，需要和子应用导出的名称一致
entry: '//localhost:8081', // 子应用入口地址
container: '#subapp-container', // 子应用挂载的容器
activeRule: '/sub-app-1', // 激活子应用的路由规则
},
{
name: 'sub-app-2',
entry: '//localhost:8082',
container: '#subapp-container',
activeRule: '/sub-app-2',
}
]);
// 启动qiankun
start();
主应用的HTML结构需要包含子应用挂载的容器：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>微前端主应用</title> </head> <body> <div id="subapp-container"></div> <script src="./main.js"></script> </body> </html>
2. 子应用开发
子应用需要导出qiankun要求的生命周期钩子，同时需要配置自身的资源路径，避免主应用加载时出现资源404的问题。
首先初始化子应用项目，这里以原生JavaScript子应用为例，子应用的核心导出逻辑如下：
// 子应用挂载逻辑
function render(props) {
const { container } = props;
// 如果是在qiankun环境中，挂载到主应用提供的容器，否则挂载到自身根节点
const mountNode = container ? container.querySelector('#sub-app-root') : document.getElementById('sub-app-root');
mountNode.innerHTML = '<h2>这是子应用1的内容</h2>';
}
// 导出qiankun生命周期
export async function bootstrap() {
console.log('子应用1 bootstrap');
}
export async function mount(props) {
console.log('子应用1 mount', props);
render(props);
}
export async function unmount(props) {
console.log('子应用1 unmount', props);
const { container } = props;
const mountNode = container ? container.querySelector('#sub-app-root') : document.getElementById('sub-app-root');
mountNode.innerHTML = '';
}
子应用的HTML结构需要包含根节点：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>子应用1</title> </head> <body> <div id="sub-app-root"></div> <script src="./sub-app.js"></script> </body> </html>
如果子应用是webpack构建的项目，还需要在webpack配置中添加如下配置，解决资源路径问题：
const packageName = require('./package.json').name;
module.exports = {
output: {
library: `${packageName}-[name]`,
libraryTarget: 'umd',
jsonpFunction: `webpackJsonp_${packageName}`,
publicPath: '//localhost:8081/', // 子应用部署的地址
},
};
3. 子应用通信
qiankun提供了基于initGlobalState的通信机制，主应用可以定义全局状态，子应用可以监听和修改全局状态：
主应用定义全局状态：
import { initGlobalState } from 'qiankun';
// 初始化全局状态
const actions = initGlobalState({
user: 'defaultUser',
token: '',
});
// 监听全局状态变化
actions.onGlobalStateChange((state, prevState) => {
console.log('主应用检测到状态变化', state, prevState);
});
// 修改全局状态
actions.setGlobalState({
user: 'newUser',
});
子应用获取和修改全局状态：
// 子应用mount生命周期中获取通信实例
export async function mount(props) {
// props中包含通信方法
props.onGlobalStateChange((state, prevState) => {
console.log('子应用1检测到状态变化', state, prevState);
});
// 修改全局状态
props.setGlobalState({
token: '123456',
});
}
部署注意事项
微前端应用部署时需要注意子应用的资源路径配置，所有子应用的入口地址需要和主应用注册的entry字段一致，同时需要解决跨域问题，子应用服务器需要配置允许主应用域名的跨域请求。如果是使用模块联邦方案，还需要注意共享模块的版本一致性，避免出现模块冲突的问题。
常见问题解决
- 子应用加载失败：检查子应用入口地址是否正确，子应用是否正常启动，是否存在跨域问题
- 样式冲突：qiankun内置了沙箱样式隔离，也可以给子应用的根节点添加唯一前缀避免冲突
- 路由跳转异常：子应用的路由需要基于主应用的
activeRule配置，避免路由路径冲突
微前端JavaScriptsingle_spaqiankun模块联邦修改时间：2026-06-13 04:30:36