企业官网建设流程全解析

1. 为什么今天还在聊 qiankun？它真不是“又一个前端框架”

微前端这个概念，从2016年被提出到现在，已经不是新鲜词了。但真正让团队敢在生产环境里大规模落地的，qiankun 是目前为数不多能扛住百万级用户、几十个子应用、持续迭代三年不翻车的方案。我带过三个中大型项目，最早用 single-spa 搭了一套，上线三个月后，每次发版都要提心吊胆——主应用一升级，某个子应用的 React 版本兼容性就崩；后来试过 Module Federation，Webpack 5 的魔法确实炫，但调试链路长、错误堆栈乱、热更新失效成了常态；直到把 qiankun 引入第三个项目，才真正体会到什么叫“解耦可控、上线安心”。

qiankun 不是框架，它是微前端的“操作系统内核”。它不强制你用 React 或 Vue，也不规定你必须写 Webpack 配置——它只做三件事：隔离沙箱、资源加载、生命周期调度。这就像给每个子应用发一套独立工位：有自己专属的 DOM 区域、独立的全局变量空间、自己的 JS 执行上下文，连样式污染都靠 CSS Scoped + 动态 style 标签注入双重兜底。你用 Vue 3 写管理后台，隔壁组用 Svelte 做数据看板，后端同事用 Python + Dash 快速搭个分析页——只要它们都遵循bootstrap/mount/unmount这三个钩子，就能塞进同一个首页里跑起来。

关键词里反复出现的“入门”“上手”“实战”，恰恰说明很多人卡在“知道概念”和“敢用线上”之间。不是不会写 demo，而是不清楚：

• 主应用怎么判断子应用是否加载失败？
• 子应用路由切换时，主应用的导航栏状态怎么同步？
• 当两个子应用都用了 moment.js，版本冲突怎么破？
• 热更新开发时，改了子应用代码，为什么主应用页面没刷新？

这些不是文档里一句“支持沙箱”就能解决的。它们藏在 qiankun 的 loader 机制里、藏在getPublicPath()的路径推导逻辑里、藏在loadMicroApp的返回值监听细节里。这篇内容，就是把我踩过的坑、压测时发现的边界、灰度发布时的回滚策略，全摊开讲清楚。不讲原理图，不列 API 表，只说你明天就要上线时，该敲哪几行代码、该配哪几个参数、该盯哪几个监控指标。

适合谁读？如果你正面临这些场景：

• 团队已有多个独立维护的 Web 应用（CRM、BI、OA），想统一入口但不想重写；
• 新业务要快速上线，但主应用技术栈老旧，不敢动；
• 大型单页应用打包体积超 10MB，首屏加载慢，拆分又怕状态混乱；
• 前后端分离后，前端团队按业务域划分，但部署流程仍强耦合。

那你不是在学 qiankun，你是在给系统装“热插拔接口”。接下来的内容，全部围绕真实战场展开。

2. 整体设计思路：为什么选 qiankun 而不是自己造轮子？

2.1 微前端不是“拆应用”，而是“建契约”

很多团队一上来就想把现有项目切成子应用，结果切完发现：登录态不共享、菜单权限不联动、跨应用跳转像跳崖。这不是技术问题，是契约缺失。qiankun 的核心价值，恰恰在于它强制定义了一套最小契约：每个子应用必须暴露bootstrap、mount、unmount三个函数，并接受props传入通信能力。这个设计看似简单，实则解决了微前端最根本的三个矛盾：

• 运行时隔离 vs 共享能力：沙箱保证 JS/CSS/HTML 互不干扰，但通过props注入router、store、message等实例，实现受控共享。比如主应用传入统一的authService，子应用调用authService.logout()会触发全局登出，而不是各自清 localStorage。

• 独立部署 vs 统一路由：子应用可以有自己的vue-router或react-router，但主应用通过createHistory创建的history实例透传过去，所有子应用的路由变更都会被主应用捕获，从而驱动顶部导航高亮、面包屑更新。我们曾用这个机制，在主应用里实现“一键返回上一业务模块”，而无需子应用主动上报。

• 技术异构 vs 体验一致：React 子应用的按钮用 Ant Design，Vue 子应用用 Element Plus，但主应用通过 CSS 变量统一控制主题色、圆角、阴影。我们在:root下定义--primary-color: #1890ff;，所有子应用的组件库都能通过var(--primary-color)响应式换肤，连第三方图表库（如 ECharts）的配色也能通过setOption动态注入。

提示：不要试图让子应用“完全自治”。qiankun 的哲学是“有限自由”——允许你用任何技术栈，但必须遵守生命周期契约。我们曾有个子应用坚持用 jQuery + Bootstarp 3，只要它把mount函数里初始化 DOM 的逻辑包好，一样能接入。关键不是技术多新，而是契约是否清晰。

2.2 qiankun 的架构分层：主应用是“交通警察”，子应用是“出租车”

理解 qiankun 架构，最好的类比是城市交通系统：

• 主应用（Main App）：相当于交管局指挥中心。它不负责修路（不写业务逻辑），只管三件事：

  1. 发布路线图（注册子应用列表及激活规则）；
  2. 调度车辆（根据当前 URL 匹配并加载对应子应用）；
  3. 处理事故（监听子应用加载失败、挂载异常、内存泄漏）。

• 子应用（Micro App）：相当于注册出租车。它必须：

  1. 安装车载终端（暴露bootstrap/mount/unmount）；
  2. 接收调度指令（响应props里的onGlobalStateChange）；
  3. 自行维护车况（独立打包、独立部署、独立监控）。

这种分层让责任边界极其清晰。主应用崩溃，子应用还能单独访问（直接输入子应用 URL）；子应用挂了，主应用首页照常显示，顶多某个菜单项变灰。我们在线上环境做过压力测试：故意让某个子应用mount函数抛错，主应用日志里只记录一条app 'crm' mount failed，其他子应用毫发无损。

注意：主应用绝不应该 import 子应用的任何代码。所有子应用资源必须通过entry字符串动态加载。我们曾因误将子应用的utils.js直接 import 到主应用，导致主应用打包体积暴增，且子应用升级时主应用必须同步发版——彻底违背微前端初衷。

2.3 为什么不用 Module Federation？它和 qiankun 的本质区别

Module Federation（MF）常被拿来和 qiankun 对比，但二者解决的问题完全不同：

我们曾在一个内部平台尝试 MF：主应用（React）想复用 BI 团队的图表组件库。结果发现，BI 团队用的是 Webpack 4，主应用是 Webpack 5，exposes导出的组件在主应用里useState报错——因为 React 的 Hooks 机制依赖特定版本的react-refresh。最后只能退回 qiankun，让 BI 团队把图表封装成独立子应用，通过props传入数据，反而更稳定。

qiankun 的优势不在“炫技”，而在“兜底”。当你的团队无法统一技术栈、无法协调发版节奏、无法保证所有成员理解 MF 的 module federation graph 时，qiankun 的显式契约就是最可靠的护栏。

3. 核心细节解析：从零搭建一个可上线的 qiankun 系统

3.1 主应用：不只是“壳”，而是“中枢神经系统”

主应用的代码量往往不到子应用的 1/10，但它承担着整个系统的稳定性。我们主应用的核心文件结构如下：

src/ ├── main.js # 入口，初始化 qiankun ├── micro-apps/ # 子应用注册配置 │ ├── crm.js # CRM 子应用配置 │ ├── bi.js # BI 子应用配置 │ └── ops.js # 运维子应用配置 ├── layouts/ # 主应用布局（含菜单、Header） │ ├── BasicLayout.vue # 基础布局，包含 <router-view> 和 <micro-app> │ └── MicroAppWrapper.vue # 封装 qiankun 的 <micro-app> 组件 └── utils/ └── qiankun.js # qiankun 初始化逻辑与错误处理

关键点在于qiankun.js的实现：

// src/utils/qiankun.js import { registerMicroApps, start, addGlobalUncaughtErrorHandler } from 'qiankun'; // 1. 全局错误兜底：捕获子应用未处理的 Promise reject addGlobalUncaughtErrorHandler((event) => { console.error('qiankun global error:', event); // 上报到 Sentry，附带子应用名称 if (event?.reason?.appName) { Sentry.captureException(event.reason, { tags: { microApp: event.reason.appName } }); } }); // 2. 子应用注册：这里不是硬编码，而是从配置文件动态加载 const apps = [ { name: 'crm', entry: '//cdn.example.com/crm/latest/main.js', // 生产环境走 CDN container: '#subapp-portal', // 挂载容器 activeRule: '/crm', // 激活规则，支持函数形式 props: { // 传递全局服务 router: router, store: store, message: ElMessage, // Element Plus 消息提示 onGlobalStateChange: handleGlobalStateChange, // 全局状态监听 setGlobalState: setGlobalState, // 全局状态设置 } }, // ... 其他子应用 ]; // 3. 启动前检查：避免重复 start let started = false; export function initQiankun() { if (!started) { registerMicroApps(apps); start({ // 关键配置：sandbox: true 是默认值，但显式写出更清晰 sandbox: { strictStyleIsolation: true }, // 启用严格样式隔离 // 加载超时：子应用 10s 内未 mount 视为失败 loadApp: async (app) => { try { return await app.load(); } catch (e) { console.error(`子应用 ${app.name} 加载失败`, e); // 触发告警：发送企业微信机器人消息 alertMicroAppFailure(app.name, 'load'); throw e; } } }); started = true; } }

实操心得：activeRule不要写死为字符串/crm。我们改成函数形式：

activeRule: (location) => { // 支持 /crm/* 和 /admin/crm 两种路径 return location.pathname.startsWith('/crm') || location.pathname.startsWith('/admin/crm'); }

这样既能适配历史路由，又能为未来权限路由留扩展空间。

3.2 子应用改造：三步走，拒绝“大手术”

子应用接入 qiankun，核心是“三改一加”：改入口、改路由、改打包、加生命周期。我们以一个 Vue 2 子应用为例：

第一步：改入口（main.js）

// 原来 new Vue({ router, store, render: h => h(App) }).$mount('#app'); // 改为 function render(props = {}) { const { container } = props; instance = new Vue({ router, store, render: h => h(App) }).$mount(container ? container.querySelector('#app') : '#app'); } // 暴露生命周期钩子 export async function bootstrap() { console.log('CRM 子应用 bootstrap'); } export async function mount(props) { console.log('CRM 子应用 mount'); render(props); } export async function unmount(props) { console.log('CRM 子应用 unmount'); instance.$destroy(); instance.$el.innerHTML = ''; }

第二步：改路由（router/index.js）

// 原来 const router = new Router({ mode: 'history', base: '/' }); // 改为：base 动态获取 const router = new Router({ mode: 'history', // 如果是子应用，base 为子应用路径；否则为 '/' base: window.__POWERED_BY_QIANKUN__ ? '/crm' : '/', });

第三步：改打包（vue.config.js）

module.exports = { configureWebpack: { output: { // 关键！library 不能写死，必须是子应用名 library: `${process.env.VUE_APP_NAME}-[name]`, libraryTarget: 'umd', jsonpFunction: `webpackJsonp_${process.env.VUE_APP_NAME}`, } }, devServer: { // 开发时代理到主应用 proxy: { '/': { target: 'http://localhost:7100', // 主应用地址 changeOrigin: true, } } } };

第四步：加公共路径（public/entry.js）

// 用于解决 webpack publicPath 在子应用中的动态计算问题 if (window.__POWERED_BY_QIANKUN__) { __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__; }

注意事项：__webpack_public_path__必须在所有模块加载前设置。我们把它放在public/entry.js，并在index.html的<head>中第一行引入：

<script src="/entry.js"></script>

3.3 样式隔离：不是“加个 scoped”，而是“建道防火墙”

qiankun 默认开启样式隔离，但实际使用中，我们发现三个关键问题：

1. CSS-in-JS 库（如 styled-components）失效：因为它们依赖document.head注入 style 标签，而沙箱里document是代理对象。解决方案：在mount时手动指定StyleSheetManager的target：

   import { StyleSheetManager } from 'styled-components'; export function mount(props) { const { container } = props; ReactDOM.render( <StyleSheetManager target={container}> <App /> </StyleSheetManager>, container.querySelector('#app') ); }

2. 第三方 UI 库的全局样式污染：比如 Ant Design 的@import '~antd/dist/antd.css'会污染主应用。解决方案：改为按需引入 + CSS Modules：

   // 不再全局 import // import 'antd/dist/antd.css'; // 改为组件内引入 import styles from './Button.module.css'; import { Button } from 'antd';

3. 字体图标（iconfont）重复加载：多个子应用都引用//at.alicdn.com/t/font_xxx.css，导致字体文件多次下载。解决方案：主应用统一加载，子应用通过props获取字体类名：

   // 主应用 props: { iconFontClass: 'iconfont' } // 子应用 <i className={`${props.iconFontClass} icon-user`}></i>

我们最终采用的样式策略是：基础层（normalize.css、字体）由主应用提供；组件层（Button/Table）各子应用独立打包；业务层（页面样式）用 CSS Modules + BEM 命名规范。这样既保证视觉一致性，又杜绝样式冲突。

4. 实操过程：从本地开发到灰度上线的完整链路

4.1 本地开发：如何让主应用和子应用同时热更新？

qiankun 官方推荐的start-qiankun方案在本地开发时体验很差——改子应用代码，主应用要手动刷新。我们自研了一套基于webpack-dev-server代理的方案：

主应用 devServer 配置：

// vue.config.js devServer: { port: 7100, proxy: { '/crm': { target: 'http://localhost:7101', // CRM 子应用开发服务器 changeOrigin: true, pathRewrite: { '^/crm': '' } // 去掉前缀 }, '/bi': { target: 'http://localhost:7102', changeOrigin: true, pathRewrite: { '^/bi': '' } } } }

子应用开发服务器启动：

# CRM 子应用 npm run serve -- --port 7101 --public-path http://localhost:7100/crm/

关键点在于--public-path参数：它告诉子应用，所有静态资源（js/css）都从http://localhost:7100/crm/加载，而主应用的 devServer 会把/crm/*请求代理到http://localhost:7101。这样：

• 主应用访问http://localhost:7100/crm，devServer 代理到http://localhost:7101；
• 子应用的main.js从http://localhost:7100/crm/main.js加载，而该请求又被代理到http://localhost:7101/main.js；
• 子应用热更新时，webpack 会向http://localhost:7100/crm/sockjs-node推送消息，主应用 devServer 会转发给子应用。

实测下来很稳：改 CRM 的 Vue 文件，保存后 1 秒内主应用页面自动刷新，且保持当前路由状态。我们还封装了一个qiankun-dev-helpernpm 包，自动注入代理配置，团队新人npm install就能开干。

4.2 构建部署：CDN + 版本号 + 回滚通道

生产环境的构建不是“npm run build”就完事。我们的标准流程：

1. 子应用构建输出目录结构：

   dist/ ├── main.js # 入口文件 ├── main.js.map # SourceMap ├── css/ # CSS 文件 │ └── app.abc123.css └── js/ # Chunk 文件 └── chunk-vendors.def456.js

2. CDN 上传脚本（upload.sh）：

   # 生成唯一版本号：git commit hash + 构建时间戳 VERSION=$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S) # 上传到 CDN，路径为 /crm/$VERSION/ aws s3 cp dist/ s3://cdn-bucket/crm/$VERSION/ --recursive # 更新 latest 指向最新版本 aws s3 cp s3://cdn-bucket/crm/$VERSION/ s3://cdn-bucket/crm/latest/ --recursive

3. 主应用配置动态化：
   主应用的micro-apps/crm.js不再硬编码entry，而是从远程 JSON 加载：

   // src/micro-apps/crm.js export default async function getCRMConfig() { const res = await fetch('//config.example.com/micro-apps.json'); const config = await res.json(); return { name: 'crm', entry: config.crm.entry, // https://cdn.example.com/crm/latest/main.js container: '#subapp-portal', activeRule: '/crm', props: { /* ... */ } }; }

这样做的好处：

• 灰度发布：修改micro-apps.json，把crm.entry指向https://cdn.example.com/crm/v1.2.0/main.js，只对 10% 用户生效；
• 秒级回滚：发现 bug，5 秒内把latest指向旧版本，或修改micro-apps.json切回上一版 URL；
• CDN 缓存控制：/crm/$VERSION/路径永不变更，CDN 可永久缓存；/crm/latest/设置短缓存（1 分钟），确保配置及时生效。

我们曾用这套方案，在一次支付模块升级中，灰度期间发现 Safari 下Intl.DateTimeFormat兼容问题，从发现问题到全量回滚，耗时 3 分钟 27 秒。

4.3 状态通信：不是“全局变量”，而是“事件总线+状态快照”

子应用间通信是高频需求，但我们严禁直接window.xxx = xxx。qiankun 提供的initGlobalState是基础，我们在此之上构建了三层通信体系：

第一层：基础状态同步（qiankun 原生）

// 主应用初始化 const actions = initGlobalState({ user: null, theme: 'light' }); // 子应用监听 actions.onGlobalStateChange((state, prevState) => { if (state.user !== prevState.user) { store.dispatch('user/setUser', state.user); } });

第二层：事件总线（基于 mitt）

// 主应用创建事件总线 import mitt from 'mitt'; const bus = mitt(); // 子应用通过 props 获取 props: { eventBus: bus } // 子应用 A 发送 props.eventBus.emit('order:created', { id: 123 }); // 子应用 B 监听 props.eventBus.on('order:created', (data) => { console.log('收到订单创建事件', data); });

第三层：状态快照（localStorage + 时间戳）
对于需要持久化的状态（如用户偏好设置），我们不依赖内存，而是写入localStorage并加时间戳：

// 主应用写入 localStorage.setItem('user-preferences', JSON.stringify({ theme: 'dark', language: 'zh-CN', timestamp: Date.now() })); // 子应用读取（带过期检查） const prefs = JSON.parse(localStorage.getItem('user-preferences') || '{}'); if (Date.now() - (prefs.timestamp || 0) < 24 * 60 * 60 * 1000) { applyPreferences(prefs); }

注意：localStorage在沙箱中是隔离的，所以必须由主应用统一写入。我们封装了useGlobalPreferencescomposable，子应用调用const { preferences, update } = useGlobalPreferences()即可。

5. 常见问题与排查技巧实录：那些文档里没写的坑

5.1 “子应用白屏”问题排查清单

这是最高频问题，原因五花八门。我们整理了标准化排查流程：

我们曾遇到一个经典案例：子应用白屏，控制台无任何错误。最后发现是子应用index.html里<div id="app"></div>写成了<div id="app"/>（自闭合标签），Vue 无法挂载。这个错误在独立运行时正常（浏览器自动补全），但在 qiankun 沙箱中 DOM 解析更严格，直接失败。

5.2 “样式丢失”问题的根因分析

样式丢失通常不是 qiankun 的锅，而是构建配置问题。我们总结了三大根源：

根源一：CSS 提取插件配置错误
Webpack 的MiniCssExtractPlugin在子应用中必须禁用，否则 CSS 不会内联到 JS 中：

// vue.config.js configureWebpack: { plugins: [ // 子应用中移除 MiniCssExtractPlugin ...(process.env.NODE_ENV === 'production' && !window.__POWERED_BY_QIANKUN__ ? [new MiniCssExtractPlugin()] : []) ] }

根源二：CSS @import 顺序错乱
子应用 CSS 中@import 'reset.css'; @import 'base.css';，但reset.css未被 qiankun 加载。解决方案：所有 CSS 必须在 JS 中import，禁止@import：

// ✅ 正确 import './reset.css'; import './base.css'; import './App.css'; // ❌ 错误 // App.css 中包含 @import 'reset.css';

根源三：动态插入的样式被沙箱拦截
ECharts 的setOption会动态创建 style 标签。解决方案：在mount时传入document：

export function mount(props) { const { container } = props; // 将子应用的 document 指向沙箱 document const chart = echarts.init(container.querySelector('#chart'), null, { renderer: 'canvas', ssr: false, width: '100%', height: '100%', // 关键：指定 document document: container.ownerDocument }); }

5.3 性能优化：从 3.2s 首屏到 1.1s 的实战经验

我们对一个包含 5 个子应用的首页做了性能优化，关键措施：

1. 资源预加载（Preload）
主应用 HTML 中添加：

<!-- 预加载即将激活的子应用 --> <link rel="preload" href="https://cdn.example.com/crm/latest/main.js" as="script"> <link rel="preload" href="https://cdn.example.com/bi/latest/main.js" as="script">

2. 子应用懒加载（Lazy Load）
非首屏子应用（如“运维监控”）延迟加载：

// 主应用路由守卫 router.beforeEach((to, from, next) => { if (to.path.startsWith('/ops')) { // 动态注册 ops 子应用 registerMicroApps([{ name: 'ops', entry: '//cdn.example.com/ops/latest/main.js', container: '#subapp-portal', activeRule: '/ops', props: { /* ... */ } }]); } next(); });

3. 沙箱性能开关
对纯展示型子应用（如帮助中心），关闭沙箱：

{ name: 'help', entry: '//cdn.example.com/help/latest/main.js', container: '#subapp-portal', activeRule: '/help', // 帮助中心无交互，关闭沙箱提升性能 sandbox: false, props: { /* ... */ } }

4. 资源合并（Resource Bundling）
将子应用的vendor.js和main.js合并为单文件，减少 HTTP 请求数：

// vue.config.js configureWebpack: { optimization: { splitChunks: { chunks: 'all', // 子应用不提取 vendor cacheGroups: { vendor: { test: /[\\/]node_modules[\\/]/, priority: -10, name: 'main' } } } } }

最终效果：Lighthouse 评分从 52 提升到 89，首屏时间（FCP）从 3.2s 降至 1.1s，子应用加载完成时间（LCP）从 4.7s 降至 1.8s。

5.4 监控告警：把“看不见的风险”变成“可运营的指标”

没有监控的微前端就是定时炸弹。我们建立了三级监控体系：

一级：加载成功率（业务层）
统计每个子应用的load/mount成功率，阈值设为 99.5%：

// 主应用中监听 addMicroAppsStatusListener((apps) => { apps.forEach(app => { if (app.status === 'LOAD_ERROR' || app.status === 'MOUNT_ERROR') { // 上报到 Prometheus prometheusCounter.inc({ app: app.name, status: app.status }); } }); });

二级：沙箱内存泄漏（运行时层）
定期检查沙箱内window属性增长：

// 每 30 秒检测 setInterval(() => { const sandbox = window.sandbox; if (sandbox && sandbox.proxyWindow) { const keys = Object.keys(sandbox.proxyWindow); if (keys.length > 1000) { // 异常增长 console.warn('沙箱 window 属性过多', keys.length); // 触发告警 alertSandboxLeak(); } } }, 30000);

三级：资源加载水印（基础设施层）
在子应用main.js开头插入水印：

// 子应用构建时注入 console.log(`%c [CRM v1.2.0] %c Loaded`, 'color: green; font-weight: bold;', 'color: gray;' );

运维通过日志系统搜索[CRM v1.2.0] Loaded，确认 CDN 部署是否成功。

这套监控上线后，我们首次在用户投诉前 8 分钟发现了 BI 子应用的mount失败，自动触发回滚，0 用户影响。

我在实际使用中发现，qiankun 最大的价值不是技术多先进，而是它把“复杂度”从代码里转移到了“契约设计”上。当你花三天时间和各团队对齐props传什么、onGlobalStateChange怎么用、错误码怎么定义时，后面半年的迭代都会变得无比顺畅。那些文档里没写的坑，其实都是沟通成本没前置消化的体现。现在我们新项目启动，第一周不写代码，只开三场“契约对齐会”，反而比直接撸码省两个月。