1. 项目概述MADEIRA 到底是什么看到“MADEIRA”这个词非前端圈的朋友第一反应多半是葡萄牙那个盛产葡萄酒和足球明星的群岛。但在前端架构领域它还有另一个身份Single-spa 官方仓库里那个非常经典的微前端示例项目。很多人在学习微前端时见过它的名字却未必认真拆过它的内部结构。MADEIRA 是一个采用 Single-spa 构建的微前端演示应用它把电商后台类业务拆分为多个独立的前端微应用分别用不同技术栈实现再通过统一的基座完成集成。简单说它解决的是“一个大型系统由多个团队独立开发、独立部署、最后还能像一个整体运行”的工程问题。无论你是刚接触微前端的新手还是在在公司里被迫接手“巨无霸前端的老兵”拿 MADEIRA 当解剖样本都能发现不少有价值的东西。这篇文章我会带着你逐层拆开 MADEIRA 的架构设计、路由组织、应用注册、依赖管理这些关键细节并结合我实际搭建微前端项目的经验把那些文档里不会明说、只有踩过坑才懂的细节一并讲透。读完之后你不仅能看懂 MADEIRA还能反推出自己项目里可复用的落地方案。2. 设计方案背后的核心逻辑2.1 一个基座N 个子应用MADEIRA 的整体设计思路可以概括为“一个基座多个微应用”。基座本身是一个 HTML 页面加一小段 JavaScript 引导代码它不承载业务逻辑只负责两件事注册子应用、监听路由变化。子应用则是真正实现业务功能的独立工程比如用户管理、订单中心、商品列表每个都可以单独开发、单独测试、单独部署。在这个模型里基座更像是房产中介自己不持有房源但知道每套房子的位置和门牌号。你告诉中介“我要去 3 号楼”也就是浏览器 URL 变化到某个前缀中介就把 3 号楼的钥匙交给你加载对应子应用。这个“中介逻辑”在 Single-spa 里由registerApplication和start两个核心 API 撑起来MADEIRA 的入口文件也是如此。为什么要把系统拆成这个形态最直接的驱动力是团队协作和发布效率。如果几百人维护一个巨型前端仓库每一次发版都牵一发动全身任何一个人的改动都可能把所有人卡在灰度流程里。拆成微应用之后团队 A 发版只需要改动自己的子应用基座和别的子应用完全不受影响。MADEIRA 用多个不同技术栈的子应用组合展示了这种独立性的极端形态——不只仓库隔离连框架都可以不同。2.2 技术栈混用本身就是一种策略MADEIRA 最让人津津乐道的一点是它故意混用了多种前端技术栈。有基于 Vue 的页面有基于 React 的页面还可能包含 Svelte、Angular 或者其他框架写的模块。这在传统单体应用里是不可想象的——团队内部可能为统一框架争论一年而在微前端架构里这种混杂反而是常态。从工程决策的角度看这套设计并非为了炫技而是为了回答一个实际问题当公司已经有了多个历史项目技术栈各不相同微前端能否让它们共存于同一个产品MADEIRA 的答案是“能”前提是子应用必须遵循 Single-spa 的生命周期协议。每种框架都被封装成标准的四个生命周期函数bootstrap、mount、unmount、update。Single-spa 根本不关心你内部用的是什么框架它只负责在合适的时间调用这些函数。就像插座不关心你用的是什么电器只要插头标准一致就能取电。MADEIRA 通过这套协议把 Vue、React 等框架揉进同一个页面导航体系靠的正是这种“约束内部、统一接口”的边界感。2.3 为什么选择 Single-spa 而不是自研框架现在很多团队一聊微前端就想自研理由通常是“别人家的框架不满足我们的场景”。但 MADEIRA 以及它背后的 Single-spa 提供的是一个更务实的思路先把基础设施的问题交给社区解决自己专注于业务模块的解耦。Single-spa 的核心机制非常薄它只处理应用加载、生命周期调度和路由匹配不规定构建工具不强制 UI 规范也不要求统一的脚手架。相比之下自研框架的隐性成本极高路由劫持的边界情况、子应用切换时的内存回收、CSS 样式隔离方案这些都需要大量实坑测试才能稳定。如果团队没有足够的精力持续维护底层框架直接基于成熟方案做二次封装是更稳妥的决策。从 MADEIRA 的目录和配置也能看出这种“薄基座”思路基座本身保持极简能下放到子应用的逻辑尽量下放。这样主应用升级迭代的频率极低长期稳定。3. 核心机制拆解与应用注册流程3.1 registerApplication 与子应用注册表MADEIRA 的启动入口通常长这样import { registerApplication, start } from single-spa; registerApplication({ name: vue-app, app: () System.import(vue-app), activeWhen: /vue, }); registerApplication({ name: react-app, app: () System.import(react-app), activeWhen: [/react, /orders], }); start();name是子应用的唯一标识注册表里不允许重名。app是一个返回 Promise 的加载函数真正执行时才去拉取子应用的 JavaScript 资源。activeWhen是路由匹配规则支持字符串前缀、路径数组或者自定义函数。这里特别需要留意的是加载函数的写法。MADEIRA 示例常常配合 SystemJS 使用System.import不只是简简单单动态加载模块它还能配合 import-map 在浏览器端解析模块名到真实 URL。这样基座代码里不需要写死每个子应用的完整地址部署时可以灵活调整版本号或回滚状态。3.2 生命周期契约每个子应用必须交付的四个函数要让 Single-spa 正确调度子应用的入口 js 必须导出生命周期函数。MADEIRA 里每个子应用都有这样一个核心文件let vueApp; export async function bootstrap(props) { // 初始化框架实例、读取公共配置 } export async function mount(props) { // 创建应用、挂载到 DOM vueApp new Vue({ router, render: h h(App), }).$mount(props.container); } export async function unmount(props) { // 销毁实例、清理事件监听 vueApp.$destroy(); }bootstrap在整个应用生命周期里只执行一次适合做缓存类的初始化。mount是每次进入子应用时执行的挂载动作unmount是离开时反挂载。Single-spa 对违背契约的处理很直接——如果子应用没有导出这些函数控制台直接报错并拒绝挂载。有一个容易踩的细节是props.container。在微前端环境里子应用不会占据整个页面而是被挂载到基座指定的某个 div 内部这样多个子应用可以共存于同一视图区域。子应用不能像独立站点那样挂到document.body上必须使用基座传入的 container。MADEIRA 的示例代码严谨地遵守了这一点。3.3 路由体系如何处理子应用切换前端微架构下最麻烦的技术点是路由自治。MADEIRA 的基座本身不渲染业务页面路由变化时它只判断“应该激活哪个子应用”然后触发对应应用的挂载/卸载。子应用内部的路由完全自理比如 Vue 子应用内部继续用 vue-routerReact 子应用内部继续用 react-router。但这里的核心问题是路由匹配顺序和重叠。MADEIRA 的注册规则里如果一个子应用的activeWhen是/vue另一个是/vue/settingsSingle-spa 会同时激活两个应用。这种场景在业务上可能有意为之但也可能造成页面重复渲染。实际项目里我倾向于让路由前缀在顶层互斥子应用内部再细分二级路由避免基座层面产生交叉激活的边界问题。对 HTML5 History 路由还需要注意基座监听popstate事件触发 re-route但子应用内部history.pushState不会自动触发基座的判断逻辑需要调用 Single-spa 提供的navigateToUrl方法确保全局路由同步更新。这个细节在 MADEIRA 示例中没有过多强调但真实项目中几乎必踩。4. 手把手复刻一个 MADEIRA 风格微前端项目4.1 准备基础工程结构下面我用一个实际可行的最小实现来复现 MADEIRA 的骨架。假设项目叫micro-shop拆成四个部分root-config基座工程负责注册和启动。layout-app公共布局包含顶部导航和侧边栏。order-app订单模块使用 Vue 3。user-app用户模块使用 React。根目录结构如下micro-shop/ ├── root-config/ ├── layout-app/ ├── order-app/ ├── user-app/ └── package.json每个子应用都是独立的 npm 工程用各自熟悉的脚手架创建。这里的关键不是统一工具链而是统一输出格式——每个子应用都要能单独构建出符合 Single-spa 生命周期的入口文件。4.2 改造子应用的构建配置以 order-app 为例Vite 作为构建工具时需要在vite.config.js里设置输出格式为systemimport { defineConfig } from vite; import vue from vitejs/plugin-vue; export default defineConfig({ plugins: [vue()], build: { target: esnext, rollupOptions: { input: src/main.js, output: { format: system, entryFileNames: order-app.js, }, }, }, server: { port: 9001, }, });format: system是这里的关键参数意思是对外输出 SystemJS 可识别的模块格式。只有用这种格式基座才能通过System.import加载并拿到生命周期函数。很多新手在这里翻车——子应用打包成普通 IIFE 或 ESM 之后基座无法识别模块导出。4.3 子应用入口导出生命周期函数order-app 的src/main.js改造如下import { createApp } from vue; import { createRouter, createWebHistory } from vue-router; import singleSpaVue from single-spa-vue; import App from ./App.vue; import routerConfig from ./router; const vueLifecycles singleSpaVue({ createApp, appOptions: { render() { return h(App); }, router: createRouter({ history: createWebHistory(), routes: routerConfig }), }, }); export const bootstrap vueLifecycles.bootstrap; export const mount vueLifecycles.mount; export const unmount vueLifecycles.unmount;这里用了官方封装好的single-spa-vue适配器它替你处理了生命周期函数和 Vue 实例创建销毁的细节。React 子应用则用single-spa-react封装原理类似都是为了把框架本身的启动/销毁过程翻译成 Single-spa 的协议语言。需要提醒的是子应用的 router base 必须和基座分配的前缀保持一致。比如 order-app 的整体前缀是/order那么 vue-router 的createWebHistory要加上base: /order否则子应用内部的二级路由会直接走根路径导致切换后页面白屏。4.4 配置 import-map 与开发联调MADEIRA 之所以能在浏览器里用模块名加载子应用靠的是 import-map。开发阶段最简单的方式是在根目录放一个import-map.json{ imports: { order-app: http://localhost:9001/order-app.js, user-app: http://localhost:9002/user-app.js, vue: https://unpkg.com/vue3/dist/vue.runtime.esm-browser.js } }基座入口里提前加载这个 import-map然后System.import(order-app)就能正确解析到本地开发服务器地址。真正部署时只需把 import-map 里的地址替换为 CDN 或静态服务器的 URL不需要改动任何业务代码。这种机制的工程价值很大你可以给不同环境维护不同的 import-map实现灰度发布时只切换某个子应用的映射地址就能完成版本切换极大降低发布风险。4.5 基座完整启动流程示例最后给出 root-config 里最小可运行的启动代码import { registerApplication, start } from single-spa; import * as System from systemjs; System.import(import-map.json).then(() { registerApplication({ name: layout-app, app: () System.import(layout-app), activeWhen: () true, }); registerApplication({ name: order-app, app: () System.import(order-app), activeWhen: /order, }); registerApplication({ name: user-app, app: () System.import(user-app), activeWhen: /user, }); start(); });activeWhen: () true表示 layout-app 在所有路由下都保持激活它负责渲染公共布局并且在自己的内部模板里放置子应用挂载点。这样用户访问/order/list时layout 始终在order-app 被激活并填进主内容区。5. 常用配置、性能优化和工作中的避坑经验5.1 子应用共享依赖的配置技巧MADEIRA 示例中共享依赖的处理值得单独拿出来讲。如果不做任何共享配置每个子应用都会把自己依赖的 Vue 或 React 打包进产物基座里同样有一份结果就是页面加载多份框架代码体积膨胀且全局状态无法互通。在 SystemJS 体系中共享依赖的玩法是import-map 里声明vue、react构建时通过external配置把框架排除在打包产物之外。Vite 子应用的构建配置增加 externalbuild: { rollupOptions: { external: [vue, vue-router], }, }这样 order-app 的产物里不再包含 Vue 源码运行时直接去 import-map 里拿共享的那一份。Base Config 这个思想在 MADEIRA 中既是简化也是限制好处是性能更优、版本强一致坏处是版本升级必须全局协调。我的建议是公共依赖尽量收敛到最小集合只共享框架核心业务组件库保持子应用独立避免基座被业务细节绑架。5.2 性能优化预加载与资源拆分微前端最常见的性能质疑是“首次进入某个子应用时资源加载白屏”。MADEIRA 这种纯懒加载方式的确存在这个体验断层。实际项目中我采用的方案是 Simple 预加载import { registerApplication } from single-spa; registerApplication({ name: user-app, app: () System.import(user-app), activeWhen: /user, }); // 部分场景允许预加载应用资源 window.addEventListener(single-spa:no-app-change, () { System.import(user-app); });核心思路是通过监听路由变化在当前空闲时提前拉取可能即将被访问的子应用资源。另外子应用内部也要做路由级代码分割别把整个子应用所有页面都打进一个 chunk。这一点和单体应用优化没有本质区别但微前端架构里更强调它——因为每个子应用加载的时机不可控代码切片越细首次可交互时间越短。关于子应用静态资源的部署路径我再多说一句。如果子应用被部署在 CDN 的某个子目录构建时必须配置正确的baseUrl或者让 SystemJS 对资源引用足够友好否则你会发现子应用渲染出来了图片全部 404。这个排查起来不算难但往往会浪费一个下午。5.3 样式隔离的三个实用方案微前端架构下样式冲突的根源是全局 CSS 不设防。MADEIRA 示例本身并没有特别复杂的样式隔离但实际落地时你必须处理组件库命名空间碰撞的问题。我实践下来有三个行之有效的方法给子应用根 DOM 节点加唯一>