微前端架构在大型项目中的落地经验：零基础入门指南

大家好，我是团队的前端培训负责人，过去三年带过二十多位应届生。很多新人刚入职时面对公司内部动辄几十万行代码的前端工程，常常一脸懵：“为什么一个页面要拆成好几个项目？怎么本地连不起来？”——其实，这背后就是微前端架构在起作用。

我当初学的时候，也以为微前端是“高大上”的黑科技，直到亲手拆了一个老项目才明白：它本质上就是把一个大应用拆成多个小应用，让不同团队能独立开发、部署和维护。今天，我就用最直白的语言，手把手带你从零搭建一个微前端项目，并分享我们在 GitHub 上开源的一些实践经验。

---

一、什么是微前端？为什么要用它？

简单理解

想象你家的客厅很大，装修时请了三拨工人：

• A 负责刷墙
• B 负责铺地板
• C 负责装灯

如果让他们同时在一个房间干活，工具乱放、互相挡路，效率极低。但如果划出三个区域，各自施工，最后再拼在一起，就高效多了。

微前端就是这个思路：把一个巨型前端应用（Monolith）拆成多个小型、独立的“微应用”，每个团队负责自己的部分，互不干扰。

典型应用场景

• 多个团队并行开发一个产品（如电商后台：商品、订单、用户中心）
• 技术栈混杂的老项目（部分 Vue 2，部分 React）
• 需要快速上线子功能，不想影响主站稳定性

📌 关键词提示：我们团队在 GitHub 上开源了一个基于 qiankun 的微前端脚手架 micro-fe-template（示例链接），里面包含完整的配置和最佳实践，欢迎 Star 和 Fork！

---

二、环境准备：5 分钟搭好开发环境

我们选用社区主流方案 qiankun（由蚂蚁金服开源），它对 Vue、React、Angular 都友好。

所需工具

工具	版本要求	安装命令
Node.js	≥ 16.x	官网下载安装
npm / yarn	最新版	npm install -g yarn

创建主应用（Main App）

# 创建主应用
npx create-react-app main-app
cd main-app
yarn start

创建子应用（Sub App）

# 创建子应用（Vue 3 示例）
npx create-vite@latest sub-app --template vue
cd sub-app
yarn dev

💡 避坑指南：很多新手卡在端口冲突！默认主应用跑在 3000，子应用跑在 5173（Vite）或 3001（Create React App）。记得在后续配置中写对端口号。

---

三、核心概念：3 个关键角色

微前端中有三个核心角色，理解它们就成功了一半：

1. 主应用（Master / Container）

• 职责：负责加载、卸载子应用，提供全局状态。
• 类比：像“房东”，提供房子（DOM 容器）和水电（公共依赖）。

2. 子应用（Micro App）

• 职责：独立运行的业务模块，可以是任何框架。
• 要求：必须暴露 bootstrap、mount、unmount 三个生命周期函数。

3. 应用注册表（Register）

• 形式：一个 JS 对象数组，告诉主应用“有哪些子应用，从哪加载”。
• 示例：

  const apps = [
    {
      name: 'sub-app',
      entry: '//localhost:5173', // 子应用入口地址
      container: '#subapp-container', // 挂载到主应用的哪个 DOM
      activeRule: '/sub' // 路由匹配规则
    }
  ];
  

✅ 新手误区纠正：子应用不需要改造成特殊格式！只需在入口文件导出那三个函数即可，其他代码照常写。

---

四、实战：一步步搭建你的第一个微前端

步骤 1：主应用集成 qiankun

# 在 main-app 目录下
yarn add qiankun

修改 src/main.js（React 项目）：

import { registerMicroApps, start } from 'qiankun';

// 注册子应用
registerMicroApps([
  {
    name: 'vue-sub-app',
    entry: '//localhost:5174', // 注意：Vite 默认是 5173，但可能被占用
    container: '#vue-container',
    activeRule: '/vue'
  }
]);

// 启动 qiankun
start();

在 public/index.html 中添加容器：

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

步骤 2：子应用改造（Vue 3）

在 sub-app/src/main.js 中：

import { createApp } from 'vue';
import App from './App.vue';

let app = null;

// 必须导出这三个函数！
export async function bootstrap() {
  console.log('Vue app bootstraped');
}

export async function mount(props) {
  app = createApp(App);
  app.mount('#app');
}

export async function unmount() {
  if (app) {
    app.unmount();
  }
}

// 独立运行时
if (!window.__POWERED_BY_QIANKUN__) {
  createApp(App).mount('#app');
}

步骤 3：解决跨域问题（开发阶段）

子应用默认不允许被 iframe 或 script 标签跨域加载。在 Vite 中配置：

sub-app/vite.config.js：

export default defineConfig({
  server: {
    port: 5174,
    // 关键：允许跨域
    cors: true,
    // 关键：允许被嵌入
    headers: {
      'Access-Control-Allow-Origin': '*'
    }
  },
  // 构建时也要注意
  build: {
    rollupOptions: {
      output: {
        // 避免 chunk 名冲突
        entryFileNames: `[name].js`,
        chunkFileNames: `[name].js`,
        assetFileNames: `[name].[ext]`
      }
    }
  }
});

步骤 4：启动并验证

# 终端 1
cd main-app && yarn start

# 终端 2
cd sub-app && yarn dev

访问 http://localhost:3000/vue，你应该能看到 Vue 子应用的内容！

🔍 调试技巧：打开浏览器控制台，输入 window.__POWERED_BY_QIANKUN__，如果返回 true，说明子应用已被 qiankun 加载。

---

五、常见问题 & 解决方案

❌ 问题 1：子应用白屏，控制台报错 “Application died in status LOADING_SOURCE_CODE”

原因：子应用入口地址（entry）写错了，或子应用未正确导出生命周期函数。

解决方案：

1. 检查 entry 是否能直接在浏览器打开（如 http://localhost:5174）
2. 确认子应用的 main.js 是否导出了 bootstrap/mount/unmount

❌ 问题 2：样式冲突，主应用的 CSS 影响了子应用

原因：CSS 是全局的，两个应用用了相同的 class 名。

解决方案：

• 短期：给子应用加 CSS Modules 或 Scoped 样式（Vue）
• 长期：约定命名空间，如子应用所有 class 前缀为 sub-xxx

❌ 问题 3：子应用无法获取主应用传递的数据

正确做法：通过 props 传递

主应用注册时：

registerMicroApps([
  {
    name: 'sub-app',
    entry: '//localhost:5174',
    container: '#vue-container',
    activeRule: '/vue',
    props: { user: { name: 'Alice' } } // 👈 传递数据
  }
]);

子应用接收：

export async function mount(props) {
  console.log(props.user); // { name: 'Alice' }
  // ...渲染逻辑
}

---

六、学习建议：从入门到进阶

第一步：动手复现本文案例

• 严格按照步骤操作，不要跳过任何细节
• 尝试把子应用换成 React（Create React App），体会“技术栈无关性”

第二步：阅读官方文档 & GitHub 源码

• qiankun 官方文档：https://qiankun.umijs.org/
• 我们团队的 GitHub 技术分享仓库：micro-fe-examples（含多框架集成、状态共享、懒加载等）

第三步：思考生产环境问题

• 如何做子应用的按需加载？
• 如何统一登录态和权限控制？
• 如何监控子应用的性能和错误？

💬 我的经验之谈：微前端不是银弹！如果你的项目只有 2 个人维护，强行拆分反而增加复杂度。先做好模块化，再考虑微前端。

---

结语

微前端的核心价值不是技术本身，而是提升大型团队的协作效率。作为新人，你不需要一开始就掌握所有细节，但要理解它的设计思想：解耦、自治、组合。

我在带实习生时常说：“先跑通一个 Hello World，再慢慢优化。”希望这篇教程能帮你迈出第一步。如果你在 GitHub 上看到我们的技术分享项目，欢迎提 Issue 讨论，或者提交 PR 补充更多场景！

🌟 记住：每一个复杂的系统，都是从一行 console.log('Hello Micro Frontend!') 开始的。加油！