《微前端架构在大型项目中的落地经验》新手入门教程

开篇：什么是微前端？为什么要用它？

大家好！欢迎来到这篇关于**微前端架构（Micro Frontends）**的初学者教程。
如果你是第一次听说这个名词，不用担心，我们会从最基础的概念讲起。

你是不是有过这些困扰？

• 做过一个大项目，代码一多就很难管理；
• 和几个团队一起开发时，代码经常冲突；
• 想引入新技术试试看，但怕影响老功能，不敢轻易改；
• 项目越来越大，部署越来越慢；

这些问题在单体前端架构中非常常见。为了解决这些问题，微前端架构应运而生。

微前端到底是什么？

你可以把它想象成“前端界的微服务”。

通俗解释：
就像把一个大蛋糕切成几块一样，微前端就是把整个前端应用拆分成多个小块（我们叫它们“子应用”），每个子应用可以由不同的技术栈开发、独立部署、互不干扰。

微前端能做什么？

• 多个团队并行开发不同功能模块，互不干扰
• 不同技术栈共存（React、Vue、Angular 甚至原生 JS）
• 快速迭代和发布新功能
• 提高整体项目的可维护性

环境准备：开发前你需要安装的东西

我们以最常见的微前端框架 —— qiankun（乾坤）为例来讲解，因为它使用简单、文档友好，非常适合初学者学习。

第一步：安装 Node.js 和 npm

请访问官网 https://nodejs.org，下载安装适合你系统的版本（推荐 LTS 版本）。

安装完成后，打开命令行工具（Windows 是 cmd，Mac 是终端 Terminal），输入下面的命令查看是否安装成功：

node -v
npm -v

输出类似这样说明安装成功：

v18.16.0
9.5.1

第二步：创建主项目（主应用）

我们将使用 vite 创建一个 Vue3 的项目作为主应用。

安装 Vite

npm create vite@latest micro-main --template vue-ts
cd micro-main
npm install

启动项目测试一下：

npm run dev

打开浏览器访问 http://localhost:5173，能看到页面正常运行即可。

第三步：创建两个子项目（子应用）

为了演示多个子应用如何共存，我们分别创建：

1. 一个基于 Vue2 的子项目（用于兼容老系统）
2. 一个基于 React 的子项目（展示跨技术栈集成）

子项目一：Vue2 子应用

vue create micro-vue2
cd micro-vue2
vue add @vueup/vue3-compat
npm install

注意，这里我们使用了一个兼容包，让 Vue2 应用可以在 Vue3 主应用中运行。

子项目二：React 子应用

npx create-react-app micro-react
cd micro-react
npm install

现在我们有三个项目：

• 主应用：micro-main（Vue3）
• 子应用一：micro-vue2（Vue2）
• 子应用二：micro-react（React）

接下来我们进入核心概念部分，理解它们是怎么协同工作的。

---

核心概念：微前端的关键术语解释

1. 主应用（Main App）

主应用是一个壳子，用来承载各个子应用。它就像一个舞台，各个子应用就像是演员，在合适的时间上台表演。

2. 子应用（Sub App）

子应用是你拆分出来的每一个功能模块或业务模块，比如商品列表页、用户中心页等。这些子应用可以自己开发、测试、上线。

3. 生命周期（LifeCycle）

这是主应用和子应用之间沟通的方式。主应用告诉子应用：“该渲染了”、“该卸载了”，子应用按照要求执行相应的操作。

4. 技术栈无关（Technology Agnostic）

你可以用 Vue、React、Angular、甚至是 jQuery 来写子应用。只要满足一定条件，就能接入到主应用中。

5. 路由管理（Routing）

主应用决定什么时候加载哪个子应用。通常我们会根据 URL 路径（如 /user）去匹配对应的子应用。

6. 公共资源（Shared Dependencies）

为了避免重复加载同一个依赖库（比如 lodash、react、vue），可以通过一些配置共享公共资源，提高性能。

---

实战项目：动手搭建一个简单的微前端项目

现在我们来一步步完成一个完整的微前端项目示例。

步骤1：在主应用中安装 qiankun 微前端框架

切换到主项目目录下：

cd micro-main
npm install qiankun --save

步骤2：修改主应用入口文件（main.ts）

编辑 src/main.ts 文件：

import { createApp } from 'vue'
import { defineCustomElements as defineVue2Components } from '@vueup/vue3-compat'
import App from './App.vue'

const app = createApp(App)
defineVue2Components(app)

app.mount('#app')

// 引入微前端
import { registerMicroApps, start } from 'qiankun';

registerMicroApps([
  {
    name: 'micro-vue2',
    entry: '//localhost:7101',
    container: '#subapp-container',
    activeRule: '/vue2',
  },
  {
    name: 'micro-react',
    entry: '//localhost:7102',
    container: '#subapp-container',
    activeRule: '/react',
  },
]);

start({
  prefetch: 'all',
});

步骤3：创建一个容器用于挂载子应用

在 App.vue 中添加一个用于装载子应用的 DOM 容器：

<template>
  <div id="app">
    <h1>我是主应用</h1>
    
    <nav>
      <router-link to="/vue2">Vue2 子应用</router-link>
      |
      <router-link to="/react">React 子应用</router-link>
    </nav>

    <!-- 子应用挂载点 -->
    <div id="subapp-container"></div>
  </div>
</template>

步骤4：启动子应用，并配置端口支持跨域

为了让主应用访问到子应用，我们需要设置子应用的运行端口，并允许跨域请求。

修改 Vue2 子应用的端口

在 micro-vue2/package.json 中添加：

"scripts": {
  "serve": "vue-cli-service serve --port 7101"
}

然后运行：

cd micro-vue2
npm run serve

确保你能通过 http://localhost:7101 访问这个项目。

修改 React 子应用的端口（需要 eject 出配置文件）

由于 Create React App 默认没有提供配置端口的功能，我们可以使用以下方式快速设置：

cd micro-react
npm run start -- -p 7102

或者更稳定的办法：使用 vite 或者手动 eject 配置。

现在我们已经准备好两个子应用了！

步骤5：运行整个项目，看看效果

现在依次打开三个项目：

项目名称	启动命令	地址
主应用	npm run dev	http://localhost:5173
Vue2 子应用	npm run serve	http://localhost:7101
React 子应用	npm run start -- -p 7102	http://localhost:7102

在主应用中点击导航栏的链接 /vue2 或 /react，应该能看到对应子应用的内容加载进来了！

🎉恭喜你，你已经完成了第一个微前端项目的搭建！

---

常见问题解答（FAQ）

Q1：为什么我访问子应用的时候报错，提示跨域？

A：这是因为子应用默认不允许外部访问它的资源，你可以做以下尝试：

• 在子应用中启用 CORS（跨域资源共享）；
• 使用反向代理统一域名；
• 开发环境直接关闭浏览器安全限制（只限本地调试）；

例如在 React 项目中加一行：

// package.json
{
  "proxy": "http://localhost:7102"
}

Q2：子应用样式为什么会污染主应用？

A：建议你在子应用中使用 scoped CSS 或 CSS Modules。也可以使用 Shadow DOM 或 iframe 包裹子应用（但 iframe 会牺牲一定的性能）。

Q3：主应用不能控制子应用的路由怎么办？

A：微前端的一个难点就是路由的协调。一种做法是主应用负责全局路由，子应用使用 HTML5 History API 进行内部跳转。

Q4：子应用之间怎么通信？

A：你可以使用全局事件总线（如 EventBus）、Redux、Vuex、或者封装一个统一的通信插件。

---

学习建议：下一步该学什么？

你现在已经掌握了微前端的基础实践技能，接下来可以深入学习以下内容：

✅ 推荐学习路径

学习阶段	学习内容	建议材料
初级	主应用与子应用的基本交互	qiankun 官网文档
中级	路由同步、数据通信、状态共享	使用 Redux/Vuex 进行通信实验
高级	性能优化、构建打包策略、部署方案	Webpack 分包、Nginx 反向代理
专家级	动态注册/卸载子应用、热更新机制等	自定义微前端框架设计与实现

🔗 推荐资料

• qiankun 官方文档：https://qiankun.umijs.org
• Single-SPA 文档（另一个流行微前端框架）：https://single-spa.js.org
• GitHub 示例代码仓库：搜索关键词 “qiankun demo”

---

结语：持续进步，才能拥抱更大的项目

微前端是一种非常实用的技术模式，尤其适合大型企业级项目。对于前端开发者来说，掌握这项技术不仅能帮助你更好地应对复杂项目，还能提升你的系统设计能力。

记住一句话：

“学会拆分，才能驾驭复杂。”

希望这篇文章能帮你顺利入门微前端世界。如果你在实践中遇到任何问题，欢迎在评论区留言交流，我会第一时间为你解答！

祝你学习愉快，早日成为前端架构高手！🌟