引言随着前端项目规模不断膨胀代码库动辄数十万行团队协作变得困难构建部署耗时也越来越长。传统的单体应用Monolith已经难以应对多团队并行开发、技术栈交叉并存的复杂场景。微前端Micro Frontends借鉴了后端微服务的思想将前端拆分为更小、更自治的“微应用”由不同团队独立开发、测试和部署最后在浏览器端通过一个容器应用将它们无缝集成。本文将先梳理微前端的核心概念随后以一个基于qiankun的完整示例展示如何从零搭建可运行的微前端架构并分享生产环境中必须解决的问题。所有代码均可直接复制运行帮助你快速上手。一、核心概念1. 什么是微前端微前端是一种架构风格将前端应用分解为多个可独立交付的垂直切片。每个微应用可以使用不同的技术栈React、Vue、Angular 甚至原生 JS拥有独立的仓库、构建流程和部署周期。主应用基座负责生命周期调度、路由分发和全局状态管理。2. 实现方式对比方案优点缺点iframe完美隔离简单易用通信繁琐性能差URL 不同步样式难以统一Web Components标准原生跨技术栈浏览器兼容性、状态管理困难生态不完善Module Federation(Webpack 5)运行时动态加载去中心化配置复杂对非 Webpack 技术栈不友好single-spa / qiankun成熟稳定开箱即用社区活跃微应用需暴露生命周期钩子改造量适中qiankun基于 single-spa封装了更为友好的 API内置样式隔离Shadow DOM / Scoped CSS和 JS 沙箱快照 / Proxy是目前业界采用最广的微前端框架下文将围绕它展开实战。二、实战用 qiankun 搭建 React React 微前端我们实现一个主应用基座和一个子应用用户 management 模块。两者均使用 Create React App 创建以便演示原生环境下的集成。完整项目结构micro-frontend-demo/ ├── main-app/ # 主应用基座 └── sub-app/ # 子应用2.1 创建主应用 main-appnpx create-react-app main-app cd main-app npm install qiankun修改src/index.js注册微应用并启动 qiankun// main-app/src/index.js import React from react; import ReactDOM from react-dom; import ./index.css; import App from ./App; import { registerMicroApps, start } from qiankun; // 主应用自身渲染 ReactDOM.render(App /, document.getElementById(root)); // 1. 注册子应用列表 registerMicroApps([ { name: sub-app, // 子应用唯一名称 entry: //localhost:3001, // 子应用运行地址开发环境 container: #sub-app-container, // 子应用挂载的 DOM 节点 activeRule: /sub, // 路由匹配规则激活子应用 }, ]); // 2. 启动 qiankun start({ sandbox: { experimentalStyleIsolation: true, // 启用 Scoped CSS 样式隔离 }, });接着在src/App.js中放置子应用的挂载容器和导航// main-app/src/App.js import React from react; import ./App.css; function App() { return ( div classNameApp header classNameApp-header h1微前端基座/h1 nav a href/Home/a | a href/sub用户管理模块/a /nav /header main {/* 子应用挂载点id 必须与 registerMicroApps 中的 container 一致 */} div idsub-app-container/div /main /div ); } export default App;为支持 qiankun 的路由匹配需要将 CRA 默认的页面刷新行为改为 history 模式但为了避免端口冲突我们仅通过activeRule做前缀匹配无需额外配置路由库。这里我们使用的是传统a标签切换路径qiankun 会监听 URL 变化并自动挂载/卸载子应用。2.2 创建子应用 sub-app同样用 CRA 创建但需注意端口设为 3001与 entry 一致npx create-react-app sub-app cd sub-app首先安装 react-router-dom用于子应用内部路由npm install react-router-dom修改src/public-path.js让子应用资源加载路径正确用于生产环境// sub-app/src/public-path.js if (window.__POWERED_BY_QIANKUN__) { // 动态设置 webpack publicPath防止资源加载 404 // eslint-disable-next-line no-undef __webpack_public_path__ window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__; }在src/index.js中暴露生命周期钩子并配置路由// sub-app/src/index.js import ./public-path; // 必须放在最顶部 import React from react; import ReactDOM from react-dom; import { BrowserRouter } from react-router-dom; import App from ./App; let root null; // 渲染函数打包为微应用和独立运行时复用 function render(props {}) { const { container } props; const dom container ? container.querySelector(#root) // 挂载到 qiankun 容器中 : document.getElementById(root); // 独立运行时挂载到 body root ReactDOM.createRoot(dom); root.render( BrowserRouter basename{window.__POWERED_BY_QIANKUN__ ? /sub : /} App / /BrowserRouter ); } // 如果是独立运行非 qiankun 环境直接渲染 if (!window.__POWERED_BY_QIANKUN__) { render(); } /** * qiankun 要求暴露三个生命周期 * bootstrap初始化仅一次 * mount挂载时调用 * unmount卸载时调用 */ export async function bootstrap() { console.log(sub-app bootstraped); } export async function mount(props) { console.log(sub-app mounted, props); render(props); } export async function unmount(props) { console.log(sub-app unmounted); if (root) { root.unmount(); // React 18 卸载方式 root null; } }为了适应子应用端口 3001在package.json中添加 dev 脚本的端口指定并允许跨域// sub-app/package.json 的 scripts 部分 scripts: { start: PORT3001 WDS_SOCKET_PORT3001 react-scripts start, ... }同时子应用的 webpack 需要配置Access-Control-Allow-Origin以便主应用加载资源时不受跨域限制。由于 CRA 默认不暴露 webpack 配置我们借助craco或直接在src/setupProxy.js中设置开发环境使用 http-proxy-middleware 是代理请求但这里是资源加载需要响应头。简单方案在子应用的src/setupProxy.js中无法直接修改 webpack-dev-server 的 headers。更直接的在package.json中加入 CORS 头npm install -D craco/craco创建craco.config.js// sub-app/craco.config.js module.exports { devServer: (devServerConfig) { devServerConfig.headers { Access-Control-Allow-Origin: *, }; return devServerConfig; }, };然后将package.json的 scripts 改为使用 cracoscripts: { start: PORT3001 craco start, build: craco build, test: craco test }最后修改子应用的App.js加入几个简单页面和路由// sub-app/src/App.js import React from react; import { Routes, Route, Link } from react-router-dom; function Home() { return h2用户管理首页/h2; } function List() { return h2用户列表/h2; } function Detail() { return h2用户详情/h2; } function App() { return ( div style{{ padding: 20, background: #f0f2f5 }} h3【子应用】用户管理/h3 nav Link to/首页/Link | Link to/list列表/Link | Link to/detail详情/Link /nav Routes Route path/ element{Home /} / Route path/list element{List /} / Route path/detail element{Detail /} / /Routes /div ); } export default App;2.3 运行验证启动子应用cd sub-app npm start访问http://localhost:3001确认子应用可独立运行。启动主应用cd main-app npm start默认在http://localhost:3000打开。点击导航栏的“用户管理模块”主应用路由变为/sub随即加载并渲染子应用。子应用的样式被隔离因为开启了experimentalStyleIsolation且能够在/sub/list等子路由下正常切换。至此一个生产可用的微前端最小原型便完成了。三、常见问题与注意事项3.1 样式隔离qiankun 提供两种样式隔离Shadow DOM 隔离strictStyleIsolation: true实验性样式完全封闭但会有细小的 UI 差异如弹窗挂载问题。Scoped CSSexperimentalStyleIsolation: true自动为所有样式规则添加一个特殊属性选择器避免污染。建议优先使用 Scoped CSS若仍存在冲突可在子应用中使用 CSS Modules 或 BEM 命名规范。3.2 JS 沙箱与全局变量污染qiankun 默认使用ProxySandbox每个微应用运行在独立的 window 代理对象中避免全局变量冲突。但若子应用使用某些浏览器原生 API如postMessage、localStorage需注意它们可能在多个子应用间共享需要设计命名空间或用通信方案隔离。3.3 微应用间通信qiankun 通过initGlobalState提供简易的全局状态管理// 主应用 import { initGlobalState } from qiankun; const actions initGlobalState({ user: admin }); actions.onGlobalStateChange((state, prev) { console.log(状态变化, state, prev); }); // 子应用可通过 props.onGlobalStateChange 和 props.setGlobalState 收发对于复杂通信建议使用自定义事件CustomEvent或公共依赖如 Redux Store 注入。3.4 公共依赖抽取多个子应用共享 React、ReactDOM 等大体积库时可在主应用通过externals排除并通过 CDN 或全局变量方式引入减少重复加载。qiankun 也支持通过getTemplate钩子自动提取公共资源。3.5 部署与 Nginx 配置生产环境中主应用和子应用需部署在同一个域名下防止跨域并配置 Nginx 的 try_files 使其正确回退到 index.htmllocation / { try_files $uri $uri/ /index.html; } location /sub { try_files $uri $uri/ /sub/index.html; }子应用的publicPath需要设置为对应的路径前缀。3.6 技术栈混合若接入 Vue 子应用需在mount钩子中实例化 Vue在unmount中销毁并注意路由的 basename。qiankun 官方文档有详细的 Vue 适配指南。四、总结微前端不是银弹它引入了一定的复杂度基座与微应用的协调、样式隔离的副作用、跨应用调试困难等。但对于大型组织、多团队协作、需要逐步迁移旧系统的场景它带来的价值远远超过成本。qiankun 通过简洁的生命周期模型、健壮的沙箱机制和丰富的插件能力极大降低了微前端的落地门槛。本文从概念到完整代码展示了 React 主应用接入 React 微应用的全过程。你可以以此为起点尝试接入不同技术栈的子应用并进一步探索自动化部署、自定义沙箱、性能监控等高级话题。希望这篇文章能帮你理清微前端的思路并让你有信心在实际项目中迈出第一步。有任何疑问欢迎在评论区交流。