微前端架构在大型项目中的落地经验：零基础也能上手的实战教程

大家好，我是一名从培训班出来的前端开发，现在也带了不少新人。今天写这篇教程，是因为我当初学微前端时踩了太多坑——资料要么太理论，要么一上来就讲 qiankun、Module Federation 这些高阶概念，根本看不懂。后来在公司参与一个大型后台系统重构，才真正理解微前端的价值。

这篇文章不讲大道理，只讲我在真实项目中用到的最佳实践，用最简单的语言 + 可运行的代码，带你从零落地一个微前端项目。哪怕你刚学完 HTML/CSS/JavaScript，也能跟着做！

---

一、微前端是啥？为啥要学它？

简单说：微前端 = 把一个大网站拆成多个小网站

想象一下：

• 你的公司有一个超级大的后台系统（比如电商后台）
• 前端团队有 50 人，分成了订单组、商品组、用户组……
• 每个组都要改同一个项目，互相冲突、上线慢、代码乱成一锅粥

微前端就是把这一个大项目，拆成多个独立的小项目：

• 商品管理是一个独立的 React 应用
• 订单管理是另一个独立的 React 应用
• 主框架（主应用）负责把它们“拼”在一起

💡 关键好处：各团队独立开发、独立部署，互不影响！

---

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

我们用最流行的 qiankun（蚂蚁开源的微前端框架）+ React

步骤 1：安装 Node.js

去 https://nodejs.org 下载 LTS 版本（建议 18.x）

验证安装：

node -v  # 应该输出 v18.x.x
npm -v   # 应该输出 9.x.x

步骤 2：创建三个项目

# 主应用（负责集成子应用）
npx create-react-app main-app

# 子应用 1：商品管理
npx create-react-app goods-app

# 子应用 2：订单管理
npx create-react-app order-app

⚠️ 注意：三个项目放在同一级目录下，方便本地调试

---

三、核心概念：3 个关键词搞懂微前端

1. 主应用（Main App）

• 就像“房东”，提供页面容器
• 负责加载和卸载子应用
• 通常包含顶部导航、侧边栏等公共区域

2. 子应用（Micro App）

• 就像“租客”，独立运行的 React 应用
• 可以有自己的路由、状态管理、样式
• 必须暴露三个生命周期函数：bootstrap、mount、unmount

3. 应用注册

• 主应用通过配置告诉 qiankun：“在哪个路径下加载哪个子应用”
• 支持本地开发（dev）和线上部署（prod）

🌟 我当初学的时候最困惑的就是生命周期，其实很简单：

• bootstrap：应用首次加载时调用（一般空着）
• mount：应用挂载到页面时调用（把 React 渲染进去）
• unmount：应用卸载时调用（清理资源）

---

四、实战项目：手把手搭建一个微前端系统

我们目标：访问 /goods 显示商品页，/order 显示订单页

第一步：改造子应用（以 goods-app 为例）

1. 安装依赖

cd goods-app
npm install --save react-app-rewired customize-cra

为什么用 react-app-rewired？因为 create-react-app 默认不让你改 webpack 配置，而微前端需要配置 umd 打包格式

2. 创建 config-overrides.js

// goods-app/config-overrides.js
const { name } = require('./package.json');
module.exports = {
  webpack: (config) => {
    config.output.library = `${name}-[name]`;
    config.output.libraryTarget = 'umd';
    config.output.globalObject = 'window';
    return config;
  },
  devServer: (configFunction) => {
    return (proxy, allowedHost) => {
      const config = configFunction(proxy, allowedHost);
      config.headers = {
        ...config.headers,
        'Access-Control-Allow-Origin': '*',
      };
      return config;
    };
  },
};

3. 修改启动命令（package.json）

{
  "scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build"
  }
}

4. 暴露生命周期函数（src/index.js）

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

function render(props = {}) {
  const { container } = props;
  const root = ReactDOM.createRoot(
    container ? container.querySelector('#root') : document.getElementById('root')
  );
  root.render(<App />);
}

// 如果是独立运行（直接访问 goods-app）
if (!window.__POWERED_BY_QIANKUN__) {
  render();
}

// 导出 qiankun 需要的三个生命周期
export async function bootstrap() {
  console.log('goods app bootstraped');
}

export async function mount(props) {
  render(props);
}

export async function unmount() {
  const root = document.getElementById('root');
  if (root) {
    ReactDOM.unmountComponentAtNode(root);
  }
}

✅ 对 order-app 做同样的改造！

---

第二步：配置主应用（main-app）

1. 安装 qiankun

cd main-app
npm install qiankun

2. 注册子应用（src/main.js）

// src/main.js
import { registerMicroApps, start } from 'qiankun';

registerMicroApps([
  {
    name: 'goods-app',
    entry: '//localhost:3001', // goods-app 的开发地址
    container: '#subapp-container',
    activeRule: '/goods',
  },
  {
    name: 'order-app',
    entry: '//localhost:3002', // order-app 的开发地址
    container: '#subapp-container',
    activeRule: '/order',
  },
]);

start();

3. 修改 App.js

// src/App.js
import { useEffect } from 'react';
import { BrowserRouter, Routes, Route, Link } from 'react-router-dom';
import './main'; // 引入微前端配置

function App() {
  return (
    <BrowserRouter>
      <div>
        {/* 顶部导航 */}
        <nav style={{ padding: '10px', background: '#f0f0f0' }}>
          <Link to="/goods" style={{ marginRight: '20px' }}>商品管理</Link>
          <Link to="/order">订单管理</Link>
        </nav>

        {/* 子应用容器 */}
        <div id="subapp-container" style={{ padding: '20px' }}></div>

        {/* 主应用自己的页面（可选） */}
        <Routes>
          <Route path="/" element={<h2>欢迎来到主应用！</h2>} />
        </Routes>
      </div>
    </BrowserRouter>
  );
}

export default App;

---

第三步：启动所有项目

开三个终端，分别运行：

# 终端 1
cd main-app && npm start  # 端口 3000

# 终端 2
cd goods-app && npm start # 端口 3001

# 终端 3
cd order-app && npm start # 端口 3002

访问 http://localhost:3000，点击导航，就能看到子应用内容了！

---

五、常见问题 & 开发心得

❓ 问题 1：子应用样式污染主应用？

原因：CSS 全局作用域
解决方案：

• 子应用使用 CSS Modules 或 styled-components
• 或者主应用用 Shadow DOM 隔离（qiankun 支持）

❓ 问题 2：子应用之间如何通信？

最佳实践：通过主应用传递 props

// 主应用注册时传入
registerMicroApps([
  {
    name: 'goods-app',
    props: { user: currentUser }, // 传给子应用
    // ...
  }
]);

// 子应用接收
export async function mount(props) {
  console.log(props.user); // 拿到数据
  render(props);
}

📌 开发心得：不要过度设计通信！90% 的场景用 props 足够了

❓ 问题 3：本地开发正常，线上部署 404？

检查点：

1. 子应用是否打包成 umd 格式（看 bundle.js 是否有 window.goods-app）
2. Nginx 是否配置了正确的跨域头
3. 主应用的 entry 地址是否指向线上 CDN

❓ 问题 4：React 版本冲突？

避坑指南：

• 主应用和子应用不要共享 React 实例
• 在子应用的 webpack 配置中把 react 设为 external（高级用法，新手先忽略）

---

六、学习建议：下一步怎么走？

学习阶段	推荐动作	预期时间
入门巩固	自己从头搭建一遍本教程	1-2 天
进阶实践	尝试加入第三个子应用（比如用户中心）	1 天
线上部署	用 GitHub Pages 部署主应用 + 子应用	2 天
深入原理	阅读 qiankun 源码（重点关注沙箱机制）	1 周+

💬 我的真心话：微前端不是银弹！如果你的项目只有 3 个人开发，别用它。它解决的是团队协作和巨型项目维护的问题。

---

最后的话

这篇教程里的每行代码，都是我在真实项目中验证过的。微前端听起来高大上，但拆解开来，无非就是：

1. 子应用打包成 umd
2. 主应用动态加载
3. 生命周期管理

不要被名词吓到。我当初也是从培训班出来，连 webpack 是啥都不知道，现在也能在大厂做架构。只要你动手敲代码，就没有学不会的技术。

如果这篇教程帮到了你，欢迎留言告诉我你的实践成果！下期我可以写《微前端 + TypeScript + Monorepo 的工程化实践》，感兴趣的话记得催更 😄