Umi

蚂蚁集团开源的可扩展企业级 React 应用框架，以插件化为核心，内置 MFSU 极速构建引擎，服务蚂蚁内部超过 10,000 个应用，是中国企业级 React 生态中最具影响力的框架之一。

技术简介说明

Umi（读作"吴米"）是由蚂蚁集团体验技术部研发的企业级前端应用框架。它以路由为基础，采用插件化架构，覆盖从源码到构建产物的完整生命周期。Umi 在蚂蚁集团内部被广泛使用，直接或间接服务超过 10,000 个应用，同时也被淘宝、飞猪、阿里云、字节跳动、腾讯、美团等头部互联网企业采用。根据字节跳动 2021 年开发者调研报告，Umi 被 25.33% 的开发者选为使用框架，是中国 React 生态中使用率最高的企业级框架之一。

Umi 4 是当前的主力版本，基于 React 18 和 React Router 6 构建，提供 Webpack 与 Vite 双引擎支持。其核心亮点 MFSU（Module Federation Speed Up）V3 将应用依赖预编译为 Module Federation Remote 应用，号称比 Vite 更快，大幅提升了大型项目的开发启动速度和热更新性能。Umi Max 作为全功能版本，将蚂蚁内部上万个项目的工程实践封装为开箱即用的工具集，内置数据流、国际化、权限、微前端等企业级能力。

与其他 React 框架相比，Umi 更聚焦于 CSR（客户端渲染）场景下的企业级应用开发，尤其在需要统一技术栈、严格约束、丰富内置功能的中后台系统中优势明显。不同于 Next.js 侧重 SSR 和全栈能力，Umi 在 CSR 场景提供了更完善的插件生态和企业级最佳实践。

基本信息

快速上手

安装

# 方式一：使用 create-umi 脚手架创建（推荐）
npx create-umi@latest myapp
 
# 方式二：创建 Umi Max（全功能版）项目
npx create-umi@latest myapp --max
 
# 方式三：使用 Ant Design Pro 模板（中后台系统）
npx create-umi@latest myapp --ant-design-pro
 
# 进入项目并安装依赖
cd myapp
pnpm install

基础配置

.umirc.ts 是 Umi 的核心配置文件：

import { defineConfig } from 'umi';
 
export default defineConfig({
  // 路由配置
  routes: [
    { path: '/', component: '@/pages/index' },
    { path: '/docs', component: '@/pages/docs' },
  ],
 
  // 启用 MFSU（Umi 4 默认开启）
  mfsu: {
    strategy: 'normal', // 或 'eager'
  },
 
  // 启用 SSR
  // ssr: {},
 
  // 启用 antd（Umi Max）
  antd: {},
 
  // 启用数据流（Umi Max）
  // initialState: {},
  // model: {},
 
  // 启用请求库（Umi Max）
  // request: {},
 
  // 启用国际化（Umi Max）
  // locale: {},
 
  // 构建引擎选择
  // vite: {},  // 使用 Vite 引擎
 
  // 代理配置
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true,
    },
  },
});

最小示例

myapp/
├── .umirc.ts              # 配置文件
├── package.json
├── src/
│   ├── pages/
│   │   ├── index.tsx       # 首页
│   │   └── docs.tsx        # 文档页
│   └── app.ts              # 运行时配置
└── tsconfig.json

// src/pages/index.tsx
import React from 'react';
 
export default function HomePage() {
  return (
    <div>
      <h1>Welcome to Umi</h1>
      <p>企业级 React 应用框架</p>
    </div>
  );
}

// src/app.ts - 运行时配置
export const layout = () => ({
  title: 'My Umi App',
});

核心概念与架构

插件系统

Umi 的核心设计理念是「一切皆插件」。框架本身的功能——包括构建、路由、请求、状态管理等——都是通过插件实现的。插件可以覆盖 Umi 的所有生命周期：

• 初始化阶段：修改配置、注册路由、注册中间件
• 构建阶段：修改 Webpack/Vite 配置、自定义构建流程
• 运行阶段：修改运行时行为、注入组件、拦截请求
• 校验阶段：通过 api.onCheck、api.onCheckConfig、api.onCheckCode 等进行代码和配置校验

// plugin.ts - 插件示例
import { IApi } from 'umi';
 
export default (api: IApi) => {
  api.modifyConfig((memo) => {
    // 修改配置
    return { ...memo, title: 'Modified' };
  });
 
  api.onCheck(() => {
    // 自定义校验逻辑
  });
};

约定式路由

Umi 支持约定式路由和配置式路由两种模式。约定式路由根据文件系统结构自动生成路由，类似 Next.js 的 Pages 目录：

src/pages/
├── index.tsx           # -> /
├── about.tsx           # -> /about
├── users/
│   ├── index.tsx       # -> /users
│   ├── [id].tsx        # -> /users/:id （动态路由）
│   └── [...all].tsx    # -> /users/* （通配路由）
├── layout.tsx          # -> 全局布局组件
└── $category/          # -> /:category/ （动态路由目录）

MFSU 构建加速

MFSU（Module Federation Speed Up）是 Umi 的核心性能优化方案。基于 Webpack 5 Module Federation，将应用源代码编译和依赖编译分离：

• Normal 策略：先编译源码同时收集依赖，串行执行，依赖收集完整
• Eager 策略：静态分析获取依赖，并行编译，速度更快（17 万行代码约 700ms）

双构建引擎

Umi 4 同时支持 Webpack 和 Vite 两种构建引擎，甚至可以在开发时用 Vite、构建时用 Webpack，给予开发者最大灵活性。

依赖预打包

Umi 采用严格的依赖预打包策略，不仅锁定 Node 侧依赖，运行时依赖（core-js、@babel/runtime）也会被锁定，确保项目长期稳定运行——官方宣称「十年后仍可稳定运行」。

核心特性

1. MFSU V3 极速构建

基于 Webpack 5 Module Federation 的打包提速方案，将应用依赖预构建为 Remote 应用。Umi 4 中默认开启，支持 Normal 和 Eager 两种策略，官方称性能超越 Vite。还支持使用 esbuild 进行依赖编译以进一步加速。

2. 完备路由系统

基于 React Router 6，类 Remix 架构，支持嵌套路由、动态路由、动态可选路由、预加载、基于路由的请求优化等高级特性。同时支持约定式路由和配置式路由，满足不同团队的需求。

3. 插件化架构

完整的生命周期插件系统，覆盖从源码到构建产物的所有环节。框架自身功能全部由插件驱动，开发者可以自由扩展和定制。支持 plugin.ts 作为默认插件文件，支持 api.onCheck 系列 API 进行团队代码规范卡点。

4. 开箱即用的企业级能力（Umi Max）

Umi Max 内置了经过蚂蚁内部万级应用验证的功能模块：数据流（valtio、react-query）、状态管理（dva、model、initial-state）、请求库、国际化（i18n）、权限管理、Ant Design 集成、图表组件、Tailwind CSS、styled-components、微前端（qiankun）等。

5. SSR & SSG 支持

支持服务端渲染（SSR）和静态站点生成（SSG），可与 CSR 混合使用。Umi 将 loader/action 机制同时应用于客户端和服务端，即使在纯 CSR 项目中也能获得优化的请求性能。

6. 白盒化与可观测

内置 ESLint、Jest 等工具链，性能指标透明可观测。通过 api.appData 收集项目元数据（配置、路由、package.json、tsconfig.json 等），为调试和监控提供支撑。

7. 多编译工具支持

灵活配置编译工具链：srcTranspiler（babel/swc/esbuild）、depTranspiler（依赖编译）、jsMinifier（esbuild/swc/terser/uglifyJs）、cssMinifier（esbuild/cssnano）。默认使用 esbuild 加速 JS/CSS 压缩。

8. Monorepo 最佳实践

提供 Monorepo 多项目管理的最佳实践，配合 pnpm workspace 和 Turbo 等工具，适合大型团队管理多个相关项目。MFSU 的 Normal 策略专门针对 Monorepo 场景做了优化。

9. 微前端集成

通过插件集成 qiankun（乾坤）微前端方案，支持将 Umi 应用作为主应用或子应用接入微前端架构。Umi Max 直接内置微前端能力。

10. Rust 构建加速（实验性）

支持接入基于 Rust 编写的 utoopack 构建工具，进一步提升编译和构建速度，代表了 Umi 在 Rust 工具链方向的探索。

生态图

Umi 插件生态

Umi 核心生态
├── umi                    # 核心框架
├── @umijs/max             # 全功能版（Umi Max）
├── @umijs/plugins         # 官方插件集合
├── create-umi             # 脚手架工具
│
├── 官方插件（部分）
│   ├── @umijs/plugin-antd          # Ant Design 集成
│   ├── @umijs/plugin-qiankun       # 微前端（乾坤）
│   ├── @umijs/plugin-locale        # 国际化
│   ├── @umijs/plugin-request       # 请求库
│   ├── @umijs/plugin-initial-state # 初始状态
│   ├── @umijs/plugin-model         # 简易数据流
│   ├── @umijs/plugin-dva           # DVA 状态管理
│   └── @umijs/plugin-layout        # 布局方案
│
└── 关联工具
    ├── dumi                   # 组件/文档工具（基于 Umi）
    ├── father                 # 库构建工具
    ├── Ant Design Pro         # 中后台解决方案模板
    └── utoopack               # Rust 构建加速（实验性）

Umi vs Umi Max

dumi 文档工具

dumi 是基于 Umi 构建的组件文档工具，支持 Markdown 渲染、代码示例展示、实时预览、主题定制等，常用于组件库文档站点的搭建。

适用场景

1. 企业级中后台系统

Umi 最核心的适用场景。配合 Ant Design 和 Ant Design Pro 模板，可快速搭建功能完善的管理后台、运营平台、数据看板等。Umi Max 内置的权限、布局、请求、状态管理等能力天然契合中后台需求。

2. 大型团队协作项目

当多个团队需要统一技术栈、开发规范和工程约束时，Umi 的插件化架构和 api.onCheck 校验能力可以强制推行团队规范，降低协作成本。

3. 需要微前端的项目

基于 qiankun 的微前端集成，适合将大型应用拆分为多个子应用独立开发部署的场景，已在蚂蚁内部大规模验证。

4. 国际化业务

内置的 i18n 插件提供完整的多语言支持，包括语言包管理、切换机制、RTL 布局等，适合面向多个国家和地区的国际化产品。

5. CSR 为主的 SPA 应用

当项目以客户端渲染为主、不需要 Next.js 那样的全栈 SSR 能力时，Umi 在 CSR 场景下的开发体验、构建速度和插件生态都更具优势。

6. Monorepo 多项目管理

为 Monorepo 提供最佳实践和专门优化（MFSU Normal 策略），配合 pnpm workspace 管理多个相关项目。

7. 长期维护的稳定项目

依赖预打包策略确保项目长期稳定运行，不受上游依赖 breaking change 影响，适合需要长期维护的企业核心系统。

开发与工程化

开发流程

# 启动开发服务器
pnpm dev          # 或 max dev
 
# 代码生成
pnpm umi generate # 或使用微生成器按需启用功能
 
# 类型检查
pnpm tsc --noEmit
 
# 代码检查
pnpm lint

构建部署

# 生产构建
pnpm build        # 或 max build
 
# 预览构建产物
pnpm preview
 
# 部署到静态服务
# 构建产物默认输出到 dist/ 目录
# 可直接部署到 Nginx、CDN 或任意静态文件服务

目录结构约定

project/
├── .umirc.ts              # 核心配置文件
├── .env                   # 环境变量
├── src/
│   ├── pages/             # 页面目录（约定式路由）
│   ├── components/        # 公共组件
│   ├── models/            # 数据模型
│   ├── services/          # API 请求服务
│   ├── utils/             # 工具函数
│   ├── locales/           # 国际化文件
│   ├── layouts/           # 自定义布局
│   ├── app.ts             # 运行时配置
│   ├── global.tsx         # 全局脚本
│   └── global.less        # 全局样式
├── config/
│   └── config.ts          # 配置式路由（可选）
├── mock/                  # Mock 数据
├── public/                # 静态资源
└── tests/                 # 测试文件

最佳实践

• 优先使用 Umi Max 获取开箱即用的企业级能力
• 利用 api.onCheck 系列 API 建立团队代码规范卡点
• 合理选择 MFSU 策略：大型项目用 Eager，Monorepo 用 Normal
• 使用 .env 文件管理环境变量，通过 UMI_APP_* 前缀约定
• 配合 @umijs/plugin-layout 快速搭建中后台布局

性能与安全

性能优化

• MFSU V3：将依赖预编译为 Module Federation Remote 应用，避免热更新时重复编译，开发环境启动速度极快
• esbuild 加速：默认使用 esbuild 进行 JS/CSS 压缩，相比 terser 有数倍提速
• 物理缓存：Webpack 5 默认开启物理缓存，减少增量构建时间
• 按需编译：srcTranspiler 支持 swc/esbuild，比传统 babel 编译速度更快
• 路由预加载：基于路由的代码分割和预加载优化首屏加载

安全注意事项

• 依赖锁定：通过严格的依赖预打包策略锁定第三方库版本，防止供应链攻击
• 运行时依赖预打包：不仅锁定 Node 侧依赖，运行时依赖也会被锁定
• XSS 防护：基于 React 的默认转义机制，配合 CSP 策略使用
• 环境变量管理：敏感信息通过 .env 文件管理，构建时注入，避免泄露到客户端
• CORS 配置：通过 proxy 配置代理请求，避免跨域安全问题

技术对比

Umi vs Next.js

官方建议：如果需要 SSR，Next.js 是更好的选择；如果只需要 CSR，Umi 是更好的选择。

Umi vs Modern.js

Umi vs Create-React-App

Umi vs Remix

最佳实践

生产环境配置

// .umirc.ts
import { defineConfig } from 'umi';
 
export default defineConfig({
  // MFSU 配置
  mfsu: {
    strategy: 'normal',
    // 排除不需要预编译的依赖
    exclude: ['some-dynamic-dep'],
  },
 
  // 编译工具配置
  srcTranspiler: 'swc',        // 源码编译使用 swc
  jsMinifier: 'esbuild',       // JS 压缩使用 esbuild
  cssMinifier: 'esbuild',      // CSS 压缩使用 esbuild
 
  // 代码分割
  codeSplitting: {
    jsStrategy: 'granularChunks',
  },
 
  // 产物分析
  analyze: {
    analyzerMode: 'server',
  },
 
  // Hash 命名（缓存优化）
  hash: true,
 
  // 公共路径
  publicPath: '/assets/',
});

团队协作规范

// 利用 api.onCheck 建立团队规范
// plugin.ts
export default (api) => {
  api.onCheck(() => {
    // 检查是否使用了禁止的 API
  });
 
  api.onCheckConfig(({ config }) => {
    // 校验配置规范
  });
 
  api.onCheckPkgJSON(({ pkgJSON }) => {
    // 检查依赖版本约束
  });
 
  api.onCheckCode(({ code }) => {
    // 自定义代码规范检查
  });
};

性能优化清单

1. 启用 MFSU 并根据项目选择合适策略
2. 使用 swc 或 esbuild 替代 babel 进行源码编译
3. 开启 Webpack 5 物理缓存
4. 合理配置代码分割策略
5. 使用 hash: true 开启文件名哈希，优化浏览器缓存
6. 生产构建时开启 Tree Shaking

技术局限与边界

已知限制

1. 不支持 IE 8 及以下浏览器：Umi 要求现代浏览器环境
2. React 版本要求：需要 React 16.8.0+（Umi 4 默认 React 18），不支持更低版本
3. Node.js 要求：运行环境需 Node.js 14+
4. 路由方案不可替换：框架内置 React Router，不支持切换到其他路由库
5. Webpack 自定义受限：框架抽象了构建配置，有强烈 Webpack 自定义需求的场景不适用
6. 生态偏中国社区：文档、教程、社区讨论以中文为主，国际化程度不如 Next.js
7. SSR 不如 Next.js 成熟：虽然支持 SSR，但核心优势在 CSR 场景，SSR 生态和部署方案不如 Next.js 完善

不适用场景

• 纯 SEO 驱动的 C 端内容站点（Next.js 或 Astro 更合适）
• 需要深度 Webpack 自定义的极特殊构建需求
• 服务端渲染为核心需求的实时应用
• 非 React 技术栈的项目
• 轻量级静态站点或博客（dumi 或 VitePress 更合适）
• 需要 Vercel 原生部署体验的项目

学习资源

官方文档

• Umi 官方文档：https://umijs.org
• Umi Max 文档：https://umijs.org/docs/max/introduce
• MFSU 指南：https://umijs.org/docs/guides/mfsu
• 升级到 Umi 4：https://umijs.org/docs/introduce/upgrade-to-umi-4
• Umi 4 RC 发布公告：https://umijs.org/blog/umi-4-rc

GitHub 资源

• Umi 主仓库：https://github.com/umijs/umi
• Umi 示例项目：https://github.com/umijs/umi/tree/master/examples
• 问题反馈：https://github.com/umijs/umi/issues
• 社区讨论：https://github.com/umijs/umi/discussions

社区与交流

• 社区论坛：https://fb.umijs.org
• 知乎专栏 — Umi 发布文章：https://zhuanlan.zhihu.com/p/531657498
• 掘金社区 Umi 相关文章：https://juejin.cn

生态工具

• Ant Design Pro（中后台模板）：https://pro.ant.design
• dumi（组件文档工具）：https://d.umijs.org
• father（库构建工具）：https://github.com/umijs/father
• 乾坤（微前端）：https://qiankun.umijs.org

2026 年现状

最新版本

截至 2026 年 7 月，Umi 最新版本为 v4.6.72，保持活跃的版本迭代。GitHub 累计 7,897+ 次提交、588+ 次发布、16,000+ Stars，是 React 生态中最活跃的中国企业级框架之一。

发展趋势

1. Umi Max 持续演进：作为蚂蚁内部 Bigfish 框架的对外版本，Umi Max 持续将内部最佳实践输出到社区，2025 年社区中关于 umi vs umi max 选型的讨论增多，说明生态正在走向成熟。
2. Rust 工具链探索：utoopack 等基于 Rust 的构建工具持续研发，有望进一步提升构建速度。
3. 双引擎策略稳定：Webpack + Vite 双引擎在 Umi 4 中已趋稳定，开发者可以按需选择。
4. 企业级生态巩固：蚂蚁内部 10,000+ 应用的持续验证使 Umi 在企业级中后台场景中保持着强劲的竞争力。

社区活跃度

• 维护团队活跃：sorrycc 等核心维护者持续投入，定期发布版本
• 社区规模稳定：16k Stars，社区论坛持续活跃
• 企业用户广泛：蚂蚁集团、阿里巴巴、字节跳动、腾讯、美团等头部企业均有使用
• 中文生态领先：在国内 React 开发者中具有较高影响力，文档和教程资源丰富