一、背景与问题
传统前端在业务发展中的典型问题
随着企业业务规模的扩大,前端系统往往呈现出多平台并行、各自演进的状态,例如:
- 财务体系下的财资平台
- 各业务线独立建设的业务管理平台
- 客服体系中的查询与运营平台
这些平台在早期能够支撑各自业务,但随着系统数量和复杂度的提升,传统前端架构逐渐暴露出一系列问题。
1. 应用割裂,资源成本高
- 各平台前端项目独立开发、独立部署
- 构建、部署、运维链路重复,基础资源(CDN、容器、域名)消耗显著
- 技术栈与工程规范不统一,长期维护成本持续上升
2. 系统分散,缺乏统一入口
- 多个平台并存,无法形成统一的业务入口
- 用户在不同系统之间频繁跳转,使用体验割裂
- 登录态、基础能力重复实现,增加整体复杂度
3. 跨系统协作效率低
- 不同业务系统之间无法灵活组合页面能力
- 业务流程需要跨系统完成时,前端改造成本高
- 难以快速支撑新业务形态或组合式应用需求
4. 菜单、路由与权限高度分散
- 菜单配置、路由定义、权限控制分散在各个系统中
- 配置口径不一致,治理难度大
- 权限调整往往需要多端同时修改,容易产生遗漏和风险
5. 整体可治理性不足
- 无法从全局视角管理应用、页面和资源
- 发布、回滚、灰度等能力只能以“系统”为单位进行
- 难以支撑企业级的统一治理与持续演进
以上问题本质上源于:前端应用以“系统”为中心进行建设,缺乏统一的应用编排与治理能力。
这也正是企业在业务规模化阶段引入微前端架构的核心动因。
二、整体架构设计
flowchart LR
%% 开发与构建
subgraph Dev[开发与构建阶段]
CLI[前端脚手架]
Build[项目打包]
Dist[构建产物]
CLI --> Build
Build --> Dist
end
%% 发布
subgraph Publish[发布阶段]
Upload[上传静态资源]
CDNStatic[CDN 静态资源]
Dist --> Upload
Upload --> CDNStatic
end
%% 后端配置中心
subgraph Backend[Node 后端配置中心]
Assets[静态资源配置]
Pages[页面配置]
Apps[应用配置]
Registry[微前端注册配置]
Assets --> Pages
Pages --> Apps
Apps --> Registry
end
%% 人工维护关系
CDNStatic -. 维护资源地址和版本 .-> Assets
%% 前端运行时
subgraph Runtime[前端运行阶段]
BaseApp[前端基座应用]
Qiankun[qiankun 运行时]
BaseApp --> Qiankun
end
%% 子应用
subgraph MicroApps[微前端子应用]
AppA[子应用 A]
AppB[子应用 B]
AppC[子应用 C]
end
%% 主链路
Dev --> Publish --> Backend --> Runtime
Registry --> BaseApp
Qiankun --> AppA
Qiankun --> AppB
Qiankun --> AppC
采用 “工程化构建 + 后端模型驱动 + 前端运行时解耦” 的整体架构,将微前端从“前端工具”升级为“企业级应用治理体系”。
从生命周期角度来看,整体架构可以划分为四个阶段:
- 开发与构建阶段
- 发布阶段
- 后端配置与编排阶段
- 前端运行阶段
下面结合架构图,对各部分进行说明。
2.1 开发与构建阶段(Dev)
该阶段的核心目标是:降低微前端子应用的创建成本,统一工程规范。
-
前端脚手架(CLI)
- 负责初始化微前端子应用项目
- 内置统一的目录结构、构建配置与运行规范
- 模板中预置 qiankun 生命周期方法,业务开发者无需关注底层细节
-
项目打包(Build)
- 通过统一的构建配置进行打包
- 保证所有子应用输出结构一致
- 避免不同项目之间因构建差异导致的运行问题
-
构建产物(Dist)
- 输出标准化的静态资源产物
- 包含子应用入口文件及其依赖资源
- 为后续 CDN 发布与配置注册提供基础
该阶段强调 工程一致性与可复制性,为规模化微前端建设打下基础。
2.2 发布阶段(Publish)
发布阶段的核心目标是:将子应用从“代码”转化为“可被注册的静态资源”。
-
上传静态资源
- 将构建产物上传至 CDN
- 支持多版本共存,便于灰度与回滚
-
CDN 静态资源
- 作为微前端子应用的最终加载入口
- 前端运行时不直接依赖构建系统,仅依赖 CDN 资源地址
在该阶段,静态资源与业务逻辑彻底解耦,为后端配置中心提供可治理的资源基础。
2.3 后端配置中心(Backend)
后端配置中心是整套架构的核心枢纽,负责对微前端进行统一建模与编排。
2.3.1 核心模型分层
后端通过三层模型对前端能力进行抽象:
-
静态资源配置(Assets)
- 描述前端构建产物的 CDN 地址、版本信息
- 与具体业务无关,仅关注资源本身
-
页面配置(Pages)
- 定义页面路由、页面名称及权限信息
- 一个页面绑定一个静态资源入口
- 页面是最小的可组合业务单元
-
应用配置(Apps)
- 表示一个完整的业务应用
- 由多个页面组合而成
- 同时承载菜单结构与业务导航信息
2.3.2 微前端注册配置生成
- 后端根据 App、Page、Asset 三层模型
- 自动生成符合 qiankun 规范的 微前端注册配置
- 并将该配置统一发布至 CDN
通过这种方式,前端不再关心“应用从哪里来”,而只关心“如何运行”。
2.4 前端运行阶段(Runtime)
前端运行阶段的核心目标是:动态加载、统一编排、按需运行微前端应用。
-
前端基座应用(Base App)
- 作为系统唯一入口
- 负责加载后端生成的注册配置
- 提供统一的布局、菜单与全局能力
-
qiankun 运行时
- 根据配置动态注册微前端子应用
- 管理子应用的加载、挂载与卸载
- 隔离各子应用的运行环境
-
微前端子应用
- 各业务系统对应的前端应用
- 独立开发、独立发布、独立运行
- 由基座在运行时进行统一调度
2.5 架构设计总结
通过上述架构设计,实现了:
- 构建与运行解耦
- 应用与页面解耦
- 配置与代码解耦
- 前端能力的统一治理与灵活编排
最终形成一套 以配置驱动为核心、以微前端为运行形态的企业级前端架构体系。
三、后端模型与配置中心设计
在企业级微前端架构中,后端不仅承担接口服务的职责,更是整个微前端体系的配置中心与应用编排中枢。
通过 Node 后端对前端静态资源、页面与应用进行统一建模,可以实现:
- 微前端运行时与构建体系解耦
- 应用、页面、资源的集中治理
- 微应用的动态注册与可控发布
- 多业务系统统一入口与菜单管理
3.1 设计目标
后端配置中心的核心设计目标包括:
- 统一管理前端静态资源及其版本生命周期
- 解耦前端路由(页面)与物理构建产物
- 通过配置驱动 qiankun 微应用注册
- 支撑多业务系统聚合为统一入口
- 保证发布、回滚、灰度过程可控
3.2 后端模型总体设计
从模型层面,后端将微前端体系拆解为 系统、应用、页面、资源 四个核心概念,并通过关系表进行解耦关联。
3.2.1 模型关系总览(ER Diagram)
erDiagram
SYSTEM_CONFIG ||--o{ APP : contains
APP ||--o{ APP_PAGE : maps
PAGE ||--o{ APP_PAGE : maps
RESOURCE ||--o{ PAGE : binds
RESOURCE ||--o{ RESOURCE_HISTORY : versions
SYSTEM_CONFIG {
string system_logo
string menu_mode
json theme_config
}
RESOURCE {
int id
string name
string js_url
string css_url
string version
string version_desc
string modifier
}
RESOURCE_HISTORY {
int id
int resource_id
string js_url
string css_url
string version
string operator
}
PAGE {
int id
string name
string path
int resource_id
}
APP {
int id
string app_code
string app_name
string app_logo
string app_desc
string app_owner
json menu_config
}
APP_PAGE {
int app_id
int page_id
string binder
}
3.3 系统配置模型(system_config)
系统配置用于描述微前端基座的全局能力,影响所有应用的运行与展示。
核心职责
- 定义系统级视觉与交互规范
- 决定菜单渲染与布局策略
- 为前端基座提供统一初始化配置
关键字段
| 字段名 | 说明 |
|---|---|
| system_logo | 系统整体标识 |
| menu_mode | 菜单模式(如侧边栏 / 顶部菜单) |
| theme_config | 主题与样式配置 |
3.4 静态资源模型(resource)
静态资源代表一次前端构建产物,是微前端运行的最小加载单元。
设计说明
- 一个资源对应一次前端构建
- 资源与业务无关,仅关注可加载性
- 支持多版本并存,便于回滚与灰度
关键字段
| 字段名 | 说明 |
|---|---|
| name | 资源名称 |
| js_url | JS 入口地址 |
| css_url | CSS 地址 |
| version | 当前版本 |
| version_desc | 版本描述 |
| modifier | 修改人 |
3.5 资源历史版本模型(resource_history)
资源历史版本模型用于记录静态资源在不同发布周期中的版本变更历史,是实现资源回滚、审计与发布可追溯性的关键支撑。
设计目标
- 记录每一次资源版本变更
- 支撑静态资源快速回滚
- 明确版本变更责任人
- 保证资源发布过程可审计、可追溯
模型结构
字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | int | 主键 ID |
| resource_id | int | 关联的静态资源 ID |
| js_url | string | 历史版本 JS 地址 |
| css_url | string | 历史版本 CSS 地址 |
| version | string | 历史版本号 |
| operator | string | 操作人 |
| created_at | datetime | 创建时间 |
3.6 页面模型(page)
页面是前端路由的抽象层,用于解耦访问路径与静态资源。
设计原则
- 页面 ≠ 具体前端项目
- 页面仅关心访问路径与资源绑定关系
- 一个资源可以承载多个页面路由
关键字段
| 字段名 | 说明 |
|---|---|
| name | 页面名称 |
| path | 路由路径 |
| resource_id | 绑定的静态资源 |
3.7 应用模型(app)
应用是业务维度的聚合单元,是用户可感知的系统模块。
设计说明
- 一个应用由多个页面组成
- 应用直接映射为系统菜单节点
- 应用是微前端注册的业务单元
3.8 应用与页面关系模型(app_page)
应用与页面之间是多对多关系,通过中间表进行解耦。
设计价值
- 页面可被多个应用复用
- 支撑跨系统页面组合
- 提高业务灵活性
3.9 微前端注册配置输出
后端配置中心最终将 应用 + 页面 + 资源 聚合为符合 qiankun 规范的注册配置,并发布至 CDN,供前端基座加载。
flowchart LR
Backend[后端配置中心]
Config[微前端注册配置]
CDN[CDN]
Backend --> Config --> CDN
示例:微前端注册配置
const registerAppList = [
{
name: "setting",
entry: {
scripts: [
"https://cdn.com/static/micro-setting/1.0.2/static/js/manifest.js",
"https://cdn.com/static/micro-setting/1.0.2/static/js/index.js"
],
styles: [
"https://cdn.com/static/micro-setting/1.0.2/static/css/index.css"
]
},
activeRule: [
"/setting/micro-setting/resource-setting/list",
"/setting/micro-setting/resource-setting/detail/:id"
]
}
]
除微前端注册配置外,后端还会同步输出:
- 系统级菜单配置
- 应用级菜单与权限配置
四、前端工程化体系(脚手架 & 构建)
在企业级微前端体系中,工程化能力决定了该方案是否可规模化落地。
如果每一个微前端子应用都需要手动配置构建、生命周期与运行规范,微前端将很快演变为新的技术负担。
因此,通过 前端脚手架 + 统一构建规范,将微前端的复杂性前置到工程体系中,对业务开发者做到开箱即用。
4.1 脚手架的设计定位
前端脚手架(CLI)在本体系中主要承担三项核心职责:
- 统一项目模板
- 封装微前端运行规范
- 收敛构建与发布流程
业务开发者只需要关注业务代码,而无需理解 qiankun、构建细节或部署约束。
4.2 CLI 能力设计
脚手架基于 commander 实现,提供最小但完整的命令集:
init:初始化微前端项目dev:启动本地开发环境build:构建微前端产物
CLI 入口示例
import { Command } from "commander";
import { init } from "./commands/init.js";
import { dev } from "./commands/dev.js";
import { build } from "./commands/build.js";
import pkg from "../package.json";
const program = new Command();
program
.name("e-micro")
.description("由 echo 提供支持的微前端 CLI 工具")
.version(pkg.version, "-v, --version", "打印版本号");
program.command("init [projectName]").action(init);
program.command("dev").action(dev);
program.command("build").action(build);
program.parse(process.argv);
模板来源策略
-
当前:直接内置在 npm 包中
-
后续规划:迁移至 GitHub Template
- 支持模板版本管理
- 支持多技术栈扩展(React / Vue)
4.3 微前端项目模板设计
模板是整个工程化体系的核心载体,其目标是:
将微前端的运行约束固化为“默认能力”,而不是“开发者约定”。
生命周期模板设计
模板内默认实现 qiankun 所需的完整生命周期,并对开发 / 生产环境进行区分处理。
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
const code = window.location.pathname.split('/')[1];
let root;
function render(props = {}) {
const { container, isDev } = props;
root = ReactDOM.createRoot(
container
? container.querySelector('#appsub')
: document.getElementById('root')
);
root.render(
<React.StrictMode>
<App basePath={isDev ? '' : code} />
</React.StrictMode>
);
}
export async function bootstrap() {
console.log('micro app bootstrap');
}
export async function mount(props) {
render(props);
}
export async function unmount() {
root.unmount();
}
export async function update(props) {
console.log('update props', props);
}
if (!window.__POWERED_BY_QIANKUN__) {
render({ isDev: true });
}
关键设计点说明
- 统一生命周期出口:避免每个子应用实现不一致
- 环境自动识别:本地开发无需基座即可运行
- basePath 动态注入:
-
- 防止子应用内部硬编码路由前缀
- 生产环境下自动拼接
package-name作为路径前缀
4.4 构建体系设计(基于 Rsbuild)
本方案选择 Rsbuild 作为构建工具,原因包括:
- 构建速度快,适合多子应用场景
- 对 rspack / webpack 生态兼容
- 配置可控,适合定制微前端输出规范
4.5 微前端构建配置规范
构建配置示例
import { defineConfig } from "@rsbuild/core";
import { pluginReact } from "@rsbuild/plugin-react";
import path from "node:path";
import fs from "node:fs";
function getPackageJson() {
const pkgPath = path.join(process.cwd(), 'package.json');
return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
}
const pkg = getPackageJson();
export default defineConfig({
source: {
define: {
__SOURCE_PREFIX__: JSON.stringify(pkg.name),
},
},
output: {
filenameHash: false,
filename: "[name].js",
assetPrefix: `https://cdn.com/static/${pkg.name}/${pkg.version}`,
},
plugins: [pluginReact()],
tools: {
rspack: (config) => {
config.output = {
...config.output,
library: pkg.name,
libraryTarget: "umd",
chunkLoadingGlobal: `webpackJsonp_${pkg.name}`,
globalObject: "window",
};
config.optimization = {
runtimeChunk: { name: "manifest" },
splitChunks: {
chunks: "async",
minSize: 0,
},
};
return config;
},
},
});
4.6 微前端构建关键约束说明
1. UMD 输出规范
library: pkg.name
libraryTarget: "umd"
globalObject: "window"
- 保证子应用可被 qiankun 正确加载
- 避免不同子应用之间的全局变量冲突
2. chunk 全局命名隔离
chunkLoadingGlobal: `webpackJsonp_${pkg.name}`
- 防止多个微应用 chunk 名称冲突
- 是企业级微前端中极易被忽略但非常关键的配置
3. 公共资源加载路径
assetPrefix: https://cdn.com/static/{package-name}/{version}
- 与后端
resource模型一一对应 - 天然支持多版本并存与回滚
- 保证分包资源正常加载
4.7 工程规范与质量控制
脚手架默认集成:
- ESLint:代码规范检查
- Prettier:统一代码风格
- 约定式目录结构:降低项目理解成本
通过工程约束,保证:
- 不同团队产出的微应用具备一致质量
- 子应用之间具备可预期的运行行为
4.8 前端构建与资源发布模型(build & deploy)
在微前端体系下,前端应用的构建与发布需要做到 自动化、标准化、环境隔离、版本可追溯。
本系统采用 CI/CD 审核通过后直接触发 deploy.sh 的方式,由脚本统一完成:
构建 → 导出产物 → 校验版本 → 上传资源
CI/CD 本身不直接执行 docker build,而是作为触发器存在,所有核心逻辑收敛在 deploy.sh 中。
4.8.1 整体流程说明
- 开发者提交代码并发起 CI/CD Pipeline
- Pipeline 完成代码检查 / 测试 / Review
- Review 通过后自动触发
deploy.sh deploy.sh内部执行:- Docker 构建前端项目
- 导出 dist 构建产物
- 校验 OSS 是否存在相同版本
- 按环境上传静态资源
- CDN / 微前端主应用按版本加载资源
4.8.2 Docker 多阶段构建(Rsbuild)
# -------------------------------
# Stage 1: 构建阶段
# -------------------------------
# 提前 docker pull node:18-alpine 和 alpine:3.19
# 可大幅减少 CI/CD 构建耗时
FROM node:18-alpine AS builder
WORKDIR /app
# 拷贝 package 文件(利用 Docker Layer Cache)
COPY package.json pnpm-lock.yaml ./
# 设置国内镜像源
RUN npm config set registry https://registry.npmmirror.com \
&& npm install -g pnpm \
&& pnpm config set registry https://registry.npmmirror.com
# 拷贝源代码
COPY . .
# 安装依赖
RUN pnpm install
# 执行构建(Rsbuild)
RUN pnpm run build
# -------------------------------
# Stage 2: 输出构建产物
# -------------------------------
FROM alpine:3.19 AS output
WORKDIR /output
# 仅复制 dist 目录,保证镜像极简
COPY --from=builder /app/dist ./dist
CMD ["echo", "✅ Rsbuild 打包完成,产物已在 /output/dist"]
4.8.3 CI/CD 触发脚本(deploy.sh)
deploy.sh 是 CI/CD Review 通过后的唯一入口脚本,负责完整的构建与发布流程。
#!/bin/bash
# ===============================
# Rsbuild 前端构建 + 资源上传
# 由 CI/CD Review 通过后触发
# ===============================
set -e
# 构建环境:dev / test / prod
ENV=${ENV:-prod}
IMAGE_NAME="rsbuild-frontend-build"
CONTAINER_NAME="rsbuild-output"
PACKAGE_NAME=$(node -p "require('./package.json').name")
PACKAGE_VERSION=$(node -p "require('./package.json').version")
LOCAL_DIR="./dist"
OSS_BUCKET="oss://cdn/static/${ENV}/${PACKAGE_NAME}/${PACKAGE_VERSION}"
echo "🌍 当前环境: $ENV"
echo "📦 包名: $PACKAGE_NAME"
echo "🏷️ 版本号: $PACKAGE_VERSION"
# Step 1: 校验 OSS 中是否已存在该版本
echo "🔍 校验资源版本是否已存在..."
if ossutilmac64 stat $OSS_BUCKET/js/index.js >/dev/null 2>&1; then
echo "❌ 版本 $PACKAGE_VERSION 已存在,请更新 package.json 中的 version"
exit 1
fi
# Step 2: 构建 Docker 镜像(内部完成 pnpm install + build)
echo "🚧 开始 Docker 构建..."
docker build -t $IMAGE_NAME .
# Step 3: 导出构建产物
echo "📦 导出 dist 构建产物..."
if [ -d "./dist" ]; then
echo "🧹 清理旧 dist 目录..."
rm -rf ./dist
fi
docker create --name $CONTAINER_NAME $IMAGE_NAME
docker cp $CONTAINER_NAME:/output/dist ./dist
docker rm $CONTAINER_NAME
# Step 4: 上传资源到 OSS
echo "☁️ 上传资源到 OSS: $OSS_BUCKET"
ossutilmac64 cp -r $LOCAL_DIR $OSS_BUCKET --update
echo "✅ 构建并上传完成"
4.8.4 CI/CD 流水线职责边界
-
CI/CD Pipeline:
- 代码检查
- 测试
- Review 审核
- 触发 deploy.sh
-
deploy.sh:
- 构建 Docker 镜像
- 前端打包
- 版本校验
- 静态资源上传
- 环境隔离(dev / test / prod)
4.8.5 构建与发布优势
-
构建逻辑完全脚本化,CI/CD 无状态
-
构建环境强一致,避免“本地能跑、线上失败”
-
静态资源天然支持:
- 环境隔离
- 版本隔离
- 回滚能力
-
适用于所有微前端子应用的统一发布规范
五、微前端运行时落地(Qiankun)
在运行时层面,系统采用 Qiankun 作为微前端框架,并以 app-base(基座应用) 作为整个企业前端体系的统一入口与运行容器。
app-base 不承载具体业务逻辑,而是负责 微应用注册、运行调度、统一布局、统一能力下沉,从而实现真正意义上的“业务解耦、体验统一”。
5.1 app-base 基座应用职责划分
app-base 是整个微前端体系的“操作系统”,核心职责包括:
- 微前端应用注册与生命周期管理
- CDN 配置拉取与动态注册
- 提供统一的 DOM 挂载节点
- 提供统一的 UI 布局(Header / Sidebar / Content)
- 提供统一的登录与鉴权能力
- 提供系统级配置与子应用管理页面
原则:
基座只做「调度与承载」,不侵入业务。
5.2 基于 CDN 的微应用注册机制
5.2.1 注册方式说明
基座启动后,不在代码中写死子应用信息,而是通过 加载 CDN 上的配置文件 完成微应用注册:
- CDN 配置来源:后端 system_config / app / resource 模型
- 配置内容:
- 应用名
- entry(JS 入口)
- activeRule(激活规则)
- container(挂载节点)
- props(下发参数)
registerMicroApps(apps, {
beforeLoad: [],
beforeMount: [],
afterUnmount: [],
});
这种方式的好处是:
- 子应用上下线 无需重新发布基座
- 支持按环境 / 按租户 / 按权限动态下发
- 与后端配置模型天然打通
5.3 统一挂载节点设计
基座应用提供一个 全局唯一的挂载容器:
<div id="micro-app-container"></div>
所有子应用在 Qiankun 生命周期中:
container由基座统一传入- 子应用只需关注自身渲染逻辑
container
? container.querySelector('#appsub')
: document.getElementById('root');
保证:
- DOM 结构稳定
- 样式隔离可控
- 子应用可独立运行 & 可被基座托管
5.4 统一布局体系(Header / Sidebar)
5.4.1 布局下沉到基座
-
Header(顶栏)
- 用户信息
- 登录态
- 系统切换
- 全局操作
-
Sidebar(侧边栏)
- 菜单树
- 子应用入口
- 权限过滤
-
Content(内容区)
- 微应用渲染区域
子应用 不感知布局存在,只在 Content 区域内运行。
5.5 菜单、路由与权限统一收敛
5.5.1 菜单来源
-
菜单由后端统一配置
-
菜单与:
- app(应用)
- page(页面)
- route(路由)
- permission(权限) 强关联
5.5.2 路由协同策略
- 一级路由:由基座控制(应用级)
- 二级及以下路由:由子应用自行维护
- activeRule 与菜单 path 保持一致
/finance → 财务应用
/finance/report → 财务子应用内部路由
5.6 子应用配置与系统配置能力
基座内置 系统级管理页面,包括但不限于:
-
子应用管理
- 应用注册信息
- CDN entry
- 启用 / 停用
- 环境配置
-
系统配置
- 全局参数
- 功能开关
- 灰度配置
-
资源配置
- 静态资源版本
- 历史版本回滚
- CDN 路径管理
这些页面本身也是 微前端理念的体现,但通常以内嵌或基座模块形式存在。
5.7 运行时落地总结
通过 app-base + Qiankun 的运行时设计,实现了:
- 微应用真正的「可配置、可插拔」
- 前端应用形态从“项目”升级为“平台”
- 菜单 / 路由 / 权限 / 登录全面收敛
- 子应用专注业务,基座专注治理
微前端的价值,不在于拆,而在于“可治理”。
六、项目源码与示例地址
为便于理解本文所述的「企业级微前端落地方案」,相关核心代码已开源,涵盖 基座应用、微前端脚手架、工程模板与配置中心 等关键模块。
📦 微前端整体解决方案(示例仓库)
- GitHub:
👉 github.com/bobowiki/mi…
该仓库主要用于展示整体架构设计、模块拆分方式以及工程协作规范。