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

大家好，我是团队的前端培训负责人，过去三年带过二十多位应届生。很多新人刚接触“微前端”这个概念时，都会一脸茫然：“这不就是把页面拆开吗？有那么复杂？”
其实我当初学的时候也是这么想的——直到第一次在真实项目里踩了坑。所以今天我想用最平实的语言，带大家从零开始理解微前端架构，并结合一个包含 Spring Boot 后端的完整示例，手把手教你如何在大型项目中真正落地它。

这篇文章不讲高深理论，只聚焦你能动手做的部分。哪怕你今天才听说“微前端”，读完也能跑通一个自己的 Demo。

---

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

简单说：微前端 = 前端界的“微服务”

想象一下：你们公司有一个超大后台系统，包含用户管理、订单处理、数据分析等多个模块。如果全部写在一个前端项目里，代码会越来越臃肿，不同团队互相冲突，发布一次要等所有人测完——效率极低。

微前端的核心思想：把一个大应用拆成多个独立的小应用（子应用），每个子应用可以：

• 由不同团队独立开发
• 使用不同技术栈（比如 Vue + React 混用）
• 独立部署上线

最终通过一个“主应用”（也叫基座应用）把它们组合在一起，用户看起来还是一个完整的网站。

✅ 关键词回顾：这就是我们常说的 技术分享 中提到的“解耦”和“自治”。

---

二、环境准备：搭建你的第一个微前端项目

我们用业界主流方案 qiankun（蚂蚁开源）+ Vue 3（主应用） + React 18（子应用） + Spring Boot（后端）来演示。

1. 安装基础工具

确保你已安装以下工具：

工具	作用	安装命令
Node.js (≥16)	运行 JavaScript 项目	官网下载
npm / yarn	包管理器	npm install -g yarn
Java 17	运行 Spring Boot	Adoptium 下载
Maven	Java 项目构建	brew install maven（Mac）或官网安装

💡 提示：我带过的应届生常犯的错误是 Node 版本太低。建议用 nvm 管理多版本。

2. 创建项目结构

我们将创建三个独立项目：

my-micro-frontend/               # 根目录
├── main-app/                   # 主应用（Vue 3）
├── react-subapp/               # 子应用（React）
└── backend/                    # Spring Boot 后端

分别初始化：

# 主应用
cd my-micro-frontend
npm create vue@3
# 项目名填 main-app，其他默认即可

# 子应用
npx create-react-app react-subapp

# 后端（稍后用）
spring init --dependencies=web backend
# 或手动创建 Spring Boot 项目

---

三、核心概念：主应用、子应用、注册机制

主应用（Main App）

• 负责路由分发
• 加载和卸载子应用
• 提供全局状态（可选）

子应用（Sub App）

• 独立运行的前端项目
• 需要暴露三个生命周期函数：
  • bootstrap()：初始化
  • mount()：挂载到 DOM
  • unmount()：卸载清理

qiankun 如何工作？

1. 主应用启动
2. 用户访问 /react 路由
3. 主应用调用 registerMicroApps() 注册子应用
4. qiankun 动态加载子应用的 JS 文件
5. 执行子应用的 mount()，渲染到指定容器

🧠 类比理解：主应用像“房东”，子应用是“租客”。房东提供房间（DOM 容器），租客自己装修（渲染 UI）。

---

四、实战：一步步搭建微前端系统

步骤 1：配置主应用（Vue 3）

进入 main-app 目录：

cd main-app
yarn add qiankun

修改 src/main.js：

import { createApp } from 'vue'
import { registerMicroApps, start } from 'qiankun'
import App from './App.vue'

const app = createApp(App)

// 注册子应用
registerMicroApps([
  {
    name: 'react-app',                 // 子应用名称
    entry: '//localhost:3001',         // 子应用入口（开发时是本地地址）
    container: '#subapp-container',    // 挂载点
    activeRule: '/react'               // 激活规则（路由前缀）
  }
])

app.mount('#app')
start() // 启动 qiankun

修改 src/App.vue，添加容器和导航：

<template>
  <div id="app">
    <nav>
      <router-link to="/">首页</router-link>
      <a href="/react">React 子应用</a>
    </nav>
    <div id="subapp-container"></div>
  </div>
</template>

⚠️ 注意：这里用 <a> 而不是 <router-link>，因为 /react 不是 Vue 路由，而是触发 qiankun 加载子应用。

步骤 2：改造子应用（React）

进入 react-subapp：

cd react-subapp
yarn add react-app-rewired customize-cra

创建 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 = {
        'Access-Control-Allow-Origin': '*',
      }
      return config
    }
  }
}

修改 package.json 启动脚本：

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

最关键：暴露生命周期函数。修改 src/index.js：

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

let root = null

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

// 如果是独立运行（非微前端模式）
if (!window.__POWERED_BY_QIANKUN__) {
  render()
}

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

export async function mount(props) {
  console.log('React app mounted')
  render(props)
}

export async function unmount() {
  console.log('React app unmounted')
  root.unmount()
}

步骤 3：启动两个前端

# 终端1：主应用
cd main-app
yarn dev  # 默认端口 5173

# 终端2：子应用
cd react-subapp
yarn start  # 默认端口 3000，但 qiankun 配置里写的是 3001？别急！

❗ 重要：CRA 默认端口是 3000，但上面配置写了 3001。有两种改法：

• 改主应用配置为 //localhost:3000
• 或改子应用端口：PORT=3001 yarn start

现在打开 http://localhost:5173，点击“React 子应用”，你应该能看到 React 页面加载出来了！

步骤 4：加入 Spring Boot 后端（模拟 API）

虽然微前端是前端架构，但实际项目离不开后端。我们简单演示如何让子应用调用 Spring Boot 接口。

创建 backend/src/main/java/com/example/demo/HelloController.java：

@RestController
public class HelloController {
    @GetMapping("/api/hello")
    public String hello() {
        return "Hello from Spring Boot!";
    }
}

启动后端（默认端口 8080）：

cd backend
./mvnw spring-boot:run

在 React 子应用中调用：

// src/App.js
useEffect(() => {
  fetch('http://localhost:8080/api/hello')
    .then(res => res.text())
    .then(data => console.log(data))
}, [])

🔒 注意：浏览器会报 CORS 错误！需在 Spring Boot 添加跨域支持：

@CrossOrigin(origins = "*")
@RestController
public class HelloController { ... }

或者更安全的做法是在开发时用代理（这里省略，重点在微前端）。

---

五、新手常见问题解答

Q1：子应用样式污染主应用怎么办？

A：qiankun 默认开启 CSS 沙箱（v2+），但建议子应用使用 CSS Modules 或 Scoped CSS。避免全局样式如 .btn。

Q2：主应用和子应用如何通信？

A：通过 props 传递。主应用注册时可传入：

registerMicroApps([
  {
    name: 'react-app',
    entry: '//localhost:3001',
    container: '#subapp-container',
    activeRule: '/react',
    props: { user: { name: 'Alice' } } // 传递数据
  }
])

子应用在 mount(props) 中接收。

Q3：生产环境怎么部署？

A：子应用构建后上传到 CDN 或 Nginx，主应用的 entry 改为线上地址，例如：

entry: 'https://cdn.example.com/react-subapp/1.0.0/'

Q4：Vue 子应用怎么写？

A：类似 React，只需暴露 bootstrap/mount/unmount。可参考 qiankun 官方 Vue 示例。

---

六、学习建议与避坑指南

下一步学什么？

1. 深入 qiankun 文档：了解预加载、沙箱隔离、公共依赖抽取
2. 尝试 Module Federation：Webpack 5 的原生微前端方案
3. 学习微前端 + 单点登录（SSO）：大型系统必备

我踩过的坑（送给你避雷）：

• ❌ 不要所有子应用都用同一套 UI 库（违背微前端初衷）
• ✅ 子应用尽量无状态，状态交给主应用或后端
• ✅ 开发时用不同端口，避免缓存干扰
• ✅ 主应用不要做业务逻辑，只做调度

---

结语

微前端不是银弹，但在大型团队协作、遗留系统迁移场景下非常有用。我带过的应届生，只要理解了“主应用调度、子应用自治”这个核心，就能快速上手。

记住：先跑通，再优化。今天你完成的这个 Demo，已经是很多公司正在用的架构雏形了。

如果你觉得这篇 技术分享 对你有帮助，不妨动手敲一遍代码。遇到问题？欢迎留言讨论——毕竟我当年也是从 Uncaught ReferenceError 一路走过来的 😄

作者：某大厂前端培训负责人
关键词：技术分享、工具、Springboot、微前端、qiankun