微前端源码精讲

前言

作者杨艺韬 · 3,064 字 · 发布于 2026-04-05 · 更新于 2026-09-24

前言

写作动机

很多团队第一次体会到"微前端不是用就行了"的那一刻，都是在生产环境被一段看似无害的 CSS 击穿的时候：

/* 子应用的"无害"样式 */
.container {
  margin: 0 auto;
  width: 100%;
  box-sizing: border-box;
}
/* 主应用也有一个 .container —— 全局布局被覆盖 */

这类事故的根因大多不在代码质量，而在对隔离机制的误解——乾坤的 strictStyleIsolation 在特定 Shadow DOM 场景下失效、ProxySandbox 的 get 拦截器为什么要特判 window 和 self、experimentalStyleIsolation 背后的 ScopedCSS 为什么要把 html、body、:root 这几个选择器单独改写、reroute 函数那看似混乱的状态机背后藏着怎样的并发控制——这些问题文档不会告诉你，只有源码会。

本专栏的写作动机只有一条：把这些必须读源码才能理解的设计决策，系统地讲清楚。

为什么在 2026 年写这个专栏

"微前端"这个词诞生于 2016 年 ThoughtWorks 的技术雷达，至今已整整十年。十年间，这个领域经历了从概念探索到生产落地、从百花齐放到格局初定的完整周期。如果你在 2020 年搜索"微前端"，几乎所有结果都指向同一个答案：乾坤。

但 2026 年的微前端世界，已经不是乾坤一家独大的时代了。

三个关键变量改变了整个格局：

Module Federation 2.0 —— Webpack 5 引入的 Module Federation 开创了"构建期声明共享模块"的范式，而 2.0 版本由 Zack Jackson 与字节跳动的 Web Infra 团队共同推进，实现了跨构建工具（Webpack/Rspack/Vite）的统一运行时。它对依赖共享走的是"构建期声明、运行期协商"：构建期只把 requiredVersion 这类版本区间写进产物，真正挑哪一份实例是运行时算的——packages/runtime-core/src/utils/share.ts 的 getRegisteredShare 里逐个 satisfy(version, requiredVersion) 比对，运行时包里甚至自带了一份 semver 实现（packages/runtime-core/src/utils/semver/）。所以它替代的是 qiankun 那套 externals + CDN 式的依赖共享，不是运行时沙箱——JS/CSS 隔离仍要另想办法（第 9、15 章会展开）。这是一次范式级的转变。

Rspack —— 字节跳动开源的基于 Rust 的构建工具，以 Webpack 兼容的 API 把构建速度提升了一个数量级。当构建时间从"等几分钟"变成"等几秒"，单体前端"构建慢"这个最常见的微前端动机之一被大幅削弱。Rspack 不是微前端框架，但它深刻地改变了微前端的决策方程式。

Wujie（无界） —— 腾讯开源的微前端方案，用 Web Components + iframe 的组合打出了一条全新路线。它没有走乾坤那条 Proxy 运行时沙箱路线，而是利用 iframe 天然的隔离能力，再通过 Web Components 实现组件级的嵌入。优雅、简洁，全局变量借 iframe 天然隔离（代价与降级模式见第 13 章）。

2016 ────── 2019 ────── 2020 ────── 2022 ────── 2024 ────── 2026
  │           │           │           │           │           │
  概念提出    乾坤 1.0     乾坤 2.0    Wujie 1.0   MF 2.0      多方案并存
  ThoughtWorks (single-spa  webpack 5   开源       Rspack 1.0  格局已变
              2015 已问世)  MF 1.0

在这个时间点写微前端架构专栏，恰好处于一个绝佳的观察窗口： 旧范式已经充分验证，新范式已经基本成型，而两者之间的张力——运行时隔离 vs 模块共享、重沙箱 vs 轻隔离、框架绑定 vs 标准原生——正是理解微前端架构本质的最佳切入点。

下图展示了微前端技术方案的演进脉络与各方案的核心定位：

flowchart TB
    SPA["single-spa (2015)\n路由即应用边界"] -.->|"实践早于命名"| Origin["2016 ThoughtWorks\n提出微前端概念"]
    Origin --> IFrame["iframe 方案\n天然隔离,体验割裂"]
    SPA --> Qiankun["乾坤 qiankun (2019)\nProxy 沙箱 + HTML Entry"]
    Qiankun --> Garfish["Garfish (字节)\nLoader/Router/Sandbox 三层分离"]
    IFrame --> Wujie["Wujie (2022)\niframe 隔离 + WebComponent 渲染"]
    WP5["webpack 5 (2020)"] --> MF1["Module Federation 1.0 (2020)\n构建期声明共享,运行期协商"]
    MF1 --> MF2["Module Federation 2.0 (2024)\n类型安全 + 运行时插件 + 跨构建工具"]
    MF2 --> Rspack["Rspack + MF 2.0\nRust 编译,构建提速一个数量级"]
    style Origin fill:#e3f2fd,stroke:#1565c0
    style Qiankun fill:#fff3e0,stroke:#e65100
    style MF2 fill:#e8f5e9,stroke:#2e7d32
    style Wujie fill:#f3e5f5,stroke:#7b1fa2
    style Rspack fill:#e8f5e9,stroke:#2e7d32

本专栏与其他微前端文章/书籍有何不同

市面上关于微前端的内容大致分为四类：

类别	典型内容	读完之后你会…
博客文章	某个框架的快速上手、踩坑记录、配置示例	知道怎么用，但不知道为什么这样设计
概念介绍书	微前端是什么、有哪些方案、架构图、决策树	能做技术选型，但遇到深层问题无从下手
单框架源码解读	逐行分析某一个框架的实现	深入理解了一个框架，但缺乏横向视野
本专栏	从源码层面横向剖析多个框架，揭示共性问题域与不同解法的设计权衡	理解微前端架构为什么这样演化，能独立评估任何方案

区别的核心在于：博客教你配置，概念书教你选择，单框架书教你一种实现，而本专栏教你理解问题本身。

下图以微前端的核心问题域为中心，展示了本专栏的知识结构与各章节的覆盖范围：

flowchart LR
    Core["微前端核心问题域"] --> Isolation["隔离机制"]
    Core --> Loading["资源加载"]
    Core --> Communication["应用通信"]
    Core --> Routing["路由调度"]
    Core --> Sharing["依赖共享"]
    Isolation --> JS["JS 沙箱\n第4章"]
    Isolation --> CSS["CSS 隔离\n第5章"]
    Isolation --> IFrame["iframe 沙箱\n第13章"]
    Loading --> HTMLEntry["HTML Entry\n第3/5章"]
    Loading --> RemoteEntry["remoteEntry.js\n第10章"]
    Communication --> GlobalState["全局状态\n第6章"]
    Communication --> Props["Props 传递\n第6章"]
    Communication --> ModuleImport["模块导入\n第9章"]
    Routing --> SingleSpa["single-spa 路由\n第7/8章"]
    Sharing --> Externals["externals 约定"]
    Sharing --> MF["Module Federation\n第9/10/11章"]
    style Core fill:#e3f2fd,stroke:#1565c0
    style Isolation fill:#ffebee,stroke:#c62828
    style Loading fill:#fff3e0,stroke:#e65100
    style Communication fill:#e8f5e9,stroke:#2e7d32
    style Routing fill:#f3e5f5,stroke:#7b1fa2
    style Sharing fill:#fffde7,stroke:#f9a825

当你理解了 JS 隔离的本质是作用域代理，CSS 隔离的本质是样式边界，应用加载的本质是资源编排，通信的本质是事件总线与共享状态的权衡——你就不再需要"选框架"了。你会直接看到每个框架在这些维度上的设计取舍，然后做出真正基于理解的决策。

教你用乾坤的文章有一千篇。教你理解乾坤为什么这样设计、以及它的设计在什么条件下会失效的——几乎没有。

本专栏读者

这个专栏为五类读者而写：

前端架构师 —— 你需要为团队做微前端技术选型，或者设计大规模前端应用的架构。本专栏的横向对比表格和设计权衡分析，会成为你决策时的参考坐标系。每个方案的优势边界和失效条件，比"哪个更好"的简单结论更有价值。

资深前端工程师 —— 你已经在用乾坤或 single-spa，但遇到了文档覆盖不到的深层问题：沙箱逃逸、样式穿透、路由冲突、性能瓶颈。本专栏从源码层面解释这些问题的根因，不是告诉你"加个配置"，而是告诉你为什么那个配置能生效、什么时候它不能。

全栈工程师 —— 你同时负责前端和后端，需要理解微前端与微服务的异同，以及前端架构如何与后端部署策略协同。本专栏的架构分析采用系统思维视角，不局限于前端领域。

技术管理者 —— 你需要评估微前端是否适合你的团队和业务场景。第 1 章的"什么时候不该用微前端"和成本分析，会帮你避免盲目跟风的代价。

学生与研究者 —— 各章的设计权衡分析和框架横向对比，可作为论文引用和研究参考。每章末附有思考题，从概念理解、源码分析延伸到实践应用和开放讨论。

不适合的读者：如果你在寻找的是"如何五分钟接入乾坤"式的快速上手指南，这个专栏不是。本专栏假设读者已具备前端开发能力，想深入理解微前端架构的底层原理和设计哲学。

前提：具备 TypeScript/JavaScript 基础和现代前端开发经验（React/Vue/Angular 至少一种）。如果你使用过至少一个微前端框架，阅读会更加顺畅。

阅读路线图

本专栏支持多种阅读方式。你可以从第 1 章顺序通读，也可以根据自身情况选择快速路径：

路径	章节	适合
快速精华	前言 → 1 → 4（JS 沙箱） → 5（CSS 隔离）	时间有限，2-3 小时获取核心架构洞察
乾坤深入	1 → 2 → 3 → 4 → 5 → 6	生产环境使用乾坤，想吃透每个细节
single-spa 专攻	1 → 2 → 7 → 8	理解微前端基座的底层路由与生命周期
架构决策	前言 → 1 → 2 → 15 → 17 → 18	架构师/技术管理者，关注选型与权衡
全景通读	按顺序从第 1 章读到最后	系统性学习者，建立完整知识体系

下图展示了不同阅读路径之间的关系与章节依赖：

flowchart TD
    Preface["前言"] --> Ch1["第1章\n为什么需要微前端"]
    Ch1 --> QiankunTrack["乾坤深入路线"]
    Ch1 --> SPATrack["single-spa 路线"]
    Ch1 --> MFTrack["Module Federation 路线"]
    Ch1 --> DecisionTrack["架构决策路线"]
    QiankunTrack --> Ch2["第2章 核心问题"]
    Ch2 --> Ch3["第3章 乾坤总览"]
    Ch3 --> Ch4["第4章 JS 沙箱"]
    Ch4 --> Ch5["第5章 CSS 隔离"]
    Ch5 --> Ch6["第6章 应用通信"]
    SPATrack --> Ch7["第7章 single-spa 核心"]
    Ch7 --> Ch8["第8章 路由拦截"]
    MFTrack --> Ch9["第9章 MF 设计哲学"]
    Ch9 --> Ch10["第10章 Webpack 5 MF 源码"]
    Ch10 --> Ch11["第11章 MF 2.0 与 Rspack"]
    DecisionTrack --> Ch15["第15章 选型决策框架"]
    Ch15 --> Ch16["第16章 DevOps"]
    Ch16 --> Ch17["第17章 性能工程"]
    Ch17 --> Ch18["第18章 设计模式"]
    style Preface fill:#e3f2fd,stroke:#1565c0
    style QiankunTrack fill:#fff3e0,stroke:#e65100
    style SPATrack fill:#f3e5f5,stroke:#7b1fa2
    style MFTrack fill:#e8f5e9,stroke:#2e7d32
    style DecisionTrack fill:#fffde7,stroke:#f9a825

工程师建议顺序通读，每章旁边打开源码，边读边调试。急性子直接翻到第 4 章乾坤 JS 沙箱，那是整个专栏最精彩的起点之一。

源码与约定

本专栏涉及多个微前端框架的源码分析，以下是各框架的版本约定：

框架	版本	说明
乾坤 (qiankun)	v2.10.16	2.x 稳定线；3.0 仍是 rc，沙箱已拆到 `@qiankunjs/sandbox`，与正文对不上
import-html-entry	v1.17.0	乾坤 HTML Entry 的底层依赖
single-spa	v6.0.3	微前端基座的事实标准
Module Federation	`module-federation/core` commit `80e9597`（2026-08-17）	该 monorepo 按包打 tag、没有仓库级版本号，所以钉 commit
webpack	v5.109.2	第 10 章拆 MF 的 webpack 侧原生实现（`lib/container/`、`lib/sharing/`）时的核查基准
Rspack	1.x	高性能构建工具，MF 2.0 的重要载体；正文对它只按公开文档与仓库结构描述，不逐行引源码
无界 (wujie)	v2.1.0	iframe + Web Components 路线

所有源码片段均从上述版本提取，标注对应文件路径与符号名（类名、函数名），行号只在少数地方给出——这些仓库重构频繁，符号名比行号活得久。部分代码为可读性做了适度简化（去除开发态日志、边界检查，简化类型标注），但核心逻辑与设计意图始终忠实保留。

代码示例统一使用 TypeScript/JavaScript。各仓库的 checkout 命令见专栏首页的「源码版本」一节。

配套资源

本专栏在线版：www.yangyitao.com/books/microfe — 持续更新
勘误与反馈：在线版每章底部均可评论反馈

本专栏对乾坤、single-spa、Module Federation、Wujie 以及所有微前端开源项目的贡献者致以谢意。kuitos（乾坤）、Joel Denning（single-spa）、Zack Jackson（Module Federation）等维护者在 GitHub Issue 与 PR 里的讨论，是本专栏许多源码解读的一手来源。

杨艺韬 2026 年春，北京