Umi 4 新特性解析及从 Umi 3 迁移指南

图 0：Umi 4 新架构全景与迁移关键路径一览

一、Umi 4 核心技术变革与新特性深度解析

Umi 作为国内广泛应用的企业级 React 前端框架，在 4.0 版本中迎来了从底层构建到顶层运行时的全面重塑。相比 Umi 3 聚焦于约定式路由与插件生态整合，Umi 4 将架构重心转向了研发体验（DX）极致提速与标准前端规范对齐。

图 1：Umi 3 与 Umi 4 底层架构与生态演进对比

1.1 双构建引擎与极速编译：MFSU v3 与 Vite 模式

在 Umi 3 中，随着项目中 node_modules 三方依赖规模增加，Webpack 每次冷启动和二次构建都需要对成千上万个模块进行抽象语法树（AST）解析与打包，构建耗时经常攀升至数分钟。

Umi 4 默认搭载了第三代模块联邦提速方案——MFSU v3（Module Federation Speed Up）。它的核心设计理念是将业务源码与三方依赖解耦：

• 依赖预编译与强缓存：利用 Go 编写的极速构建工具 esbuild，在首次启动时将所有未变动的三方依赖（如 react、antd、lodash 等）预打包为符合 Webpack Module Federation 规范的联邦独立 Chunk。
• 业务增量轻量编译：Webpack 仅需要专注编译开发人员编写的业务代码，遇到依赖时直接指向已编译好的模块联邦容器，完全跳过了对庞大 node_modules 的重复遍历。
• 秒级冷启动与瞬时 HMR：根据实际工程测算，MFSU v3 使大型项目的热启动时间从原先的 60~120 秒骤降至 1~3 秒以内，文件保存后的热更新（HMR）响应稳定在毫秒级。
• 原生 Vite 支持：除了 Webpack 5 + MFSU 外，Umi 4 原生内置了对 Vite 构建引擎的支持。在配置文件中简单声明 vite: {}，即可直接切入基于 ES 模块原生的高速开发环境。

图 2：Umi 4 核心技术机制：MFSU v3 构建加速与 Route Data Loader 并行预取

1.2 全面支持 React 18 并发特性

Umi 4 的运行时基石全面升级至 React 18。框架默认启用了 React 18 的 createRoot 挂载 API，带来了以下架构红利：

• 全自动批处理（Automatic Batching）：在 React 17 及以前，只有合成事件回调中的多次 setState 会被合并；而在 React 18 中，无论是在 Promise.then、setTimeout 还是原生事件回调中，多次状态修改都会统一合并为一次重新渲染，极大减少了不必要的组件重绘。
• 并发渲染与过渡 Hooks：项目可直接使用 useTransition、useDeferredValue 等并发调度工具，将耗时的过滤、搜索渲染标记为非阻塞更新，优先保障用户输入等高优先级交互的顺畅响应。

1.3 现代路由体系革新：React Router v6 与 Route Data Loader

Umi 3 采用的是 React Router v5，其路由配置在处理深层嵌套页面结构时，往往需要依赖额外的 _layout.tsx 文件并通过 props.children 逐级传递，容易造成布局混乱且无法灵活复用。Umi 4 全面接入 React Router v6，实现了路由机制的代际升级：

• 原生嵌套路由与 Outlet 模式：在 Umi 4 中，父级页面通过引入 <Outlet /> 组件占位渲染子路由内容，路由层级结构清晰明了，严格对应 URL 路径树。
• 消除 exact 配置冗余：React Router v6 采用基于评分机制（Ranked Matching）的最优路径匹配算法，所有路由默认遵循精准匹配原则，不再需要像 Umi 3 那样在每个路由条目上手动添加 exact: true。
• Route Data Loader（数据预加载机制）：传统前端单页应用常陷入“下载组件代码 ➔ 挂载渲染 ➔ 触发 useEffect ➔ 发起 HTTP 请求”的串行网络瀑布流（Waterfall），导致用户必须先经历骨架屏或 Loading 动画。Umi 4 引入了路由级 Data Loader，在路由匹配发生时，框架能够并行下载页面组件 JS 和发起数据加载请求。当组件完成渲染时，数据已在内存中就绪，直接调用 useLoaderData() 即可同步获取数据，彻底消除了白屏等待时间。

1.4 企业级解决方案收敛：从零散插件到 @umijs/max

在 Umi 3 时代，搭建企业级后台系统通常需要在 package.json 中引入大量的独立插件，例如 @umijs/plugin-initial-state、@umijs/plugin-model、@umijs/plugin-access、@umijs/plugin-request、@umijs/plugin-layout 等，容易导致版本不一致、类型冲突和配置繁琐。

Umi 4 针对这一痛点推出了统一的企业级套件 @umijs/max。它将中后台核心场景所需的微前端（qiankun）、权限控制（Access）、全局简易状态管理（Model）、请求封装（Request）、ProLayout 以及国际化模块完全收敛为单一依赖包，并在配置项中通过布尔值或简单对象即可一键开箱即用。

二、迁移前的环境评估与准备工作

在开展正式迁移前，需要对原 Umi 3 项目的环境配置与依赖清单进行完整盘点，确认符合 Umi 4 的技术前置基线。

2.1 Node.js 运行环境与包管理器要求

Umi 4 深度依赖 Node.js 新版本的高性能底层特性与 Web 规范 API：

• Node.js 版本：必须保证本地开发与 CI/CD 构建机器的 Node.js 版本处于 ^14.18.0 || >=16.0.0 范围，生产环境强烈建议统一升级至 Node.js 18.x LTS 或 Node.js 20.x LTS。
• 包管理器：推荐使用 pnpm（>= 7.0）或 npm（>= 8.0）。如果使用 pnpm，因其严格的软链接拓扑结构，建议在根目录 .npmrc 中补充配置 auto-install-peers=true。

2.2 现有项目技术栈梳理与废弃依赖盘点

在升级前，需对 package.json 进行清理，下表列出了迁移中必须剔除或替换的常见依赖项：

三、从 Umi 3 到 Umi 4 的标准化迁移实操步骤

遵循系统性的五步实施法，可以最大限度规避跨大版本升级中的连带问题。

图 3：从 Umi 3 升级至 Umi 4 的标准化五步实施路线图

步骤一：更新 package.json 依赖定义

对于典型的中后台管理系统，建议直接采用 @umijs/max 替代原先分散的 Umi 3 依赖。修改项目根目录下的 package.json：

{
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "antd": "^4.20.0",
    "@ant-design/pro-layout": "^6.5.0"
  },
  "devDependencies": {
    "umi": "^3.5.20",
    "@umijs/preset-react": "^1.8.30",
    "@umijs/plugin-model": "^1.4.2",
    "@umijs/plugin-initial-state": "^2.4.0",
    "typescript": "^4.1.2"
  }
}

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "antd": "^4.24.0",
    "@ant-design/pro-components": "^2.3.0"
  },
  "devDependencies": {
    "@umijs/max": "^4.0.0",
    "typescript": "^4.9.0"
  }
}

# 清理历史缓存及依赖
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml src/.umi
# 重新安装最新依赖
pnpm install # 或 npm install

步骤二：重写与精简配置文件 config.ts

Umi 4 移除了大量已过时或由底层引擎自动接管的旧配置项。例如：

• fastRefresh: {}：Umi 4 底层默认启用 React Fast Refresh，该选项已被移除。
• dynamicImport: {}：代码分包机制升级，不再需要手动配置。
• nodeModulesTransform: {}：统一由 MFSU 与 esbuild 处理，无需显式声明编译级别。
• mfsu: {}：在 Umi 4 中默认开启（如果需要自定义配置，可声明对象形式）。
• 路由定义中的 exact: true：由于 React Router 6 原生精确匹配，需全部删除。

// Umi 3: config/config.ts
import { defineConfig } from 'umi';

export default defineConfig({
  nodeModulesTransform: { type: 'none' },
  fastRefresh: {},
  dynamicImport: {
    loading: '@/components/PageLoading',
  },
  routes: [
    {
      path: '/',
      component: '@/layouts/BasicLayout',
      routes: [
        { path: '/', exact: true, redirect: '/welcome' },
        { path: '/welcome', exact: true, component: './Welcome' },
        { path: '/users/:id', exact: true, component: './Users/Detail' },
      ],
    },
  ],
  mfsu: {},
});

// Umi 4: config/config.ts
import { defineConfig } from '@umijs/max';

export default defineConfig({
  npmClient: 'pnpm',
  // 声明开启的企业级套件功能
  layout: {
    title: '企业管理系统',
  },
  model: {},
  initialState: {},
  request: {},
  access: {},
  // 现代路由定义：无需 exact，支持嵌套与布局
  routes: [
    {
      path: '/',
      component: '@/layouts/BasicLayout',
      routes: [
        { path: '', redirect: '/welcome' },
        { path: 'welcome', component: './Welcome' },
        { path: 'users/:id', component: './Users/Detail' },
      ],
    },
  ],
  // 开启高性能 MFSU 预编译引擎
  mfsu: {
    strategy: 'normal',
  },
});

步骤三：重构路由组织与页面组件

这是从 Umi 3 迁移到 Umi 4 中对业务代码变动最大、也最需要细致处理的环节。由于 React Router 从 v5 跃迁至 v6，原先的注入式 props 与部分经典 Hooks 均已调整。

1. 布局组件由 props.children 改用 <Outlet />

在 Umi 3 的父级布局组件中，子路由页面是通过 props.children 传入并渲染的；而在 Umi 4 中，必须改用 <Outlet /> 占位组件。

// src/layouts/BasicLayout.tsx (Umi 3)
import React from 'react';
import { IRouteComponentProps } from 'umi';

const BasicLayout: React.FC<IRouteComponentProps> = (props) => {
  return (
    <div className="layout-container">
      <header>系统导航头</header>
      <main>
        {/* 旧版直接渲染 children */}
        {props.children}
      </main>
    </div>
  );
};
export default BasicLayout;

// src/layouts/BasicLayout.tsx (Umi 4)
import React from 'react';
import { Outlet } from '@umijs/max'; // 或 from 'umi'

const BasicLayout: React.FC = () => {
  return (
    <div className="layout-container">
      <header>系统导航头</header>
      <main>
        {/* 新版使用标准 Outlet 占位 */}
        <Outlet />
      </main>
    </div>
  );
};
export default BasicLayout;

2. 路由跳转与参数读取 API 映射

React Router 6 弃用了 useRouteMatch 以及在组件 props 中直接注入 match、location、history 的旧模式，改由更加规范的 Hooks 系列接管：

// src/pages/Users/Detail.tsx (Umi 3)
import React from 'react';
import { IRouteComponentProps, history } from 'umi';

const UserDetail: React.FC<IRouteComponentProps<{ id: string }>> = (props) => {
  const userId = props.match.params.id;
  const filterType = props.location.query?.type;

  const handleBack = () => {
    history.push('/users');
  };

  return (
    <div>
      <h3>用户ID: {userId}, 类别: {filterType}</h3>
      <button onClick={handleBack}>返回列表</button>
    </div>
  );
};
export default UserDetail;

// src/pages/Users/Detail.tsx (Umi 4)
import React from 'react';
import { useParams, useSearchParams, useNavigate } from '@umijs/max';

const UserDetail: React.FC = () => {
  // 通过标准 Hooks 解构路由参数
  const { id: userId } = useParams();
  const [searchParams] = useSearchParams();
  const filterType = searchParams.get('type');
  const navigate = useNavigate();

  const handleBack = () => {
    navigate('/users');
  };

  return (
    <div>
      <h3>用户ID: {userId}, 类别: {filterType}</h3>
      <button onClick={handleBack}>返回列表</button>
    </div>
  );
};
export default UserDetail;

步骤四：运行时配置 src/app.tsx 适配与插件对齐

在 src/app.tsx 中，getInitialState、layout、request 等运行时配置依然是核心。Umi 4 对这些配置项的返回结构与类型声明进行了标准化规范：

// src/app.tsx (Umi 4 / @umijs/max)
import type { RequestConfig, RunTimeLayoutConfig } from '@umijs/max';
import { history } from '@umijs/max';

// 1. 全局初始状态获取（通常用于鉴权与用户信息拉取）
export async function getInitialState(): Promise<{ currentUser?: API.UserInfo; name?: string }> {
  const token = localStorage.getItem('access_token');
  if (!token && history.location.pathname !== '/login') {
    history.push('/login');
    return {};
  }
  try {
    // 调用统一 request 获取用户信息
    const res = await queryCurrentUser();
    return { currentUser: res.data, name: res.data.name };
  } catch (error) {
    history.push('/login');
    return {};
  }
}

// 2. ProLayout 运行时定制
export const layout: RunTimeLayoutConfig = ({ initialState }) => {
  return {
    logo: 'https://img.alicdn.com/tfs/TB1YHEpwUT1gK0jSZFhXXaAtVXa-28-27.svg',
    menu: {
      locale: false,
    },
    logout: () => {
      localStorage.removeItem('access_token');
      history.push('/login');
    },
    childrenRender: (children) => {
      return <>{children}</>;
    },
  };
};

// 3. 网络请求配置（基于 axios 的轻量封装）
export const request: RequestConfig = {
  timeout: 10000,
  headers: { 'X-Requested-With': 'XMLHttpRequest' },
  requestInterceptors: [
    (config: any) => {
      const token = localStorage.getItem('access_token');
      if (token) {
        config.headers.Authorization = `Bearer ${token}`;
      }
      return config;
    },
  ],
  responseInterceptors: [
    (response: any) => {
      const { data } = response;
      if (data?.code !== 0 && data?.code !== 200) {
        console.error('业务接口错误:', data?.message);
      }
      return response;
    },
  ],
};

步骤五：微前端与跨页面状态升级

如果原项目在 Umi 3 中使用了 qiankun 微前端 或 dva / useModel：

• 微前端 qiankun：无需再引入 @umijs/plugin-qiankun。在 config/config.ts 中直接设置 qiankun: { master: { ... } } 或 qiankun: { slave: { ... } } 即可。在主应用中，微应用路由定义可以直接通过挂载点接入，保持子应用独立沙箱隔离。
• 简易数据流 Model：在 src/models 目录下的 Hook 函数依然遵循原生规范，通过 export default () => { ... } 导出，页面内使用 useModel('modelName') 取值保持完全兼容，但需注意状态更新时不要触发多余的重复渲染。

四、常见迁移问题排查与避坑指南

在迁移实际项目时，往往会遭遇因历史遗留代码与新规范冲突导致的问题。以下汇总了高频的四大典型异常及其直接修复方案。

图 4：Umi 3 迁移到 Umi 4 常见报错与排障解决方案速查

4.1 问题一：页面白屏且报错 Cannot read property 'children' of undefined

原因排查：项目内部自定义了多层全局 Layout（如 SecurityLayout、UserLayout 等），组件声明沿用了 (props) => { return props.children }。在 React Router 6 下，子路由元素由 Router Context 单独驱动，不再作为 children 注入给组件。

解决方案：检查所有 src/layouts/ 下的布局组件以及路由配置中指定为父级的组件，将其内部渲染逻辑统一修改为 import { Outlet } from 'umi'; return <Outlet />;。

4.2 问题二：TypeScript 报错 Module 'umi' has no exported member 'useRouteMatch'

原因排查：旧代码中广泛使用了 React Router 5 提供的 useRouteMatch、useHistory 或旧版类型 IRouteComponentProps。Umi 4 已经将路由底层切换为 React Router 6，这些导出已被废弃。

解决方案：全局检索代码中的 useRouteMatch，如果用于获取路径参数，替换为 useParams()；如果用于获取当前路径，替换为 useLocation().pathname；如果使用 useHistory，替换为 useNavigate()。

4.3 问题三：控制台警告 Plugin 'model' / 'initialState' registered multiple times

原因排查：在 package.json 中同时保留了旧的独立插件包（如 @umijs/plugin-model）与 @umijs/max，或者 .umirc.ts 中依然写着 plugins: ['@umijs/plugin-model']，导致插件重复初始化。

解决方案：从 package.json 中彻底移除所有 @umijs/plugin-* 相关包；清理配置文件中的 plugins 字段，统一在顶层开启简短配置（例如 model: {}）。

4.4 问题四：MFSU 预编译卡死或 Module Federation 共享实例版本冲突

原因排查：本地磁盘中仍残留有 Umi 3 构建生成的 src/.umi 缓存文件、node_modules/.cache 或 Webpack 缓存；或者在 Monorepo 架构中，子模块与主工程存在多份不同版本的 antd 或 react。

解决方案：

1. 彻底清除本地缓存：执行 rm -rf src/.umi node_modules/.cache .mfsu。
2. 重新执行元数据同步指令：npx umi setup，强制生成契合当前工程配置的 .umi 运行时文件。
3. 如果存在第三方库单例限制，在 config/config.ts 的 mfsu 配置中显式声明共享依赖：

   // 保证 antd 与 react 全局单例
   export default defineConfig({
     mfsu: {
       shared: {
         react: { singleton: true },
         'react-dom': { singleton: true },
         antd: { singleton: true },
       },
     },
   });

五、产物验证与生产环境上线测试

完成上述步骤后，进入最终的本地走查与生产构建验收阶段。

5.1 本地开发初始化与 dev 走查

首次迁移完成后，切勿直接执行 dev 脚本，应优先初始化工程元数据：

# 1. 重建 .umi 核心元数据（生成类型声明与路由清单）
npx umi setup

# 2. 启动本地研发服务器（观察首次 MFSU 预编译进度）
npx umi dev # 或 pnpm dev

在控制台输出中，可重点观察：

• 首次启动时，控制台将显示 [MFSU] compile 3rd-party dependencies...，耗时约 5~10 秒完成依赖预编译。
• 随后控制台输出本地访问地址（如 http://localhost:8000），刷新浏览器页面验证各核心模块交互、路由传参与权限守卫功能。

5.2 生产构建产物检查与部署校验

验证本地功能无误后，执行正式构建命令：

# 执行生产环境优化构建
npx umi build

构建成功后，在 dist/ 目录下会生成优化后的静态资源文件。可通过以下方式进行部署前校验：

• 产物预览：执行 npx umi preview 启动静态文件预览服务器，排查是否有静态资源路径（publicPath）加载失败或 CSS 样式错乱。
• 产物分析：若需深度优化首屏体积，可在配置中加入 ANALYZE=1 umi build，观察各 Chunk 的体积构成，利用 Tree-shaking 剔除未使用的冗余组件。

总结

从 Umi 3 升级至 Umi 4 是一次收益显著的技术栈跃迁。借由 MFSU v3 编译解耦与 React Router v6 现代路由规范，研发团队不仅能彻底摆脱大型项目开发启动缓慢与热更新卡顿的困扰，还能以更规范的架构享受 React 18 并发特质与 Route Data Loader 带来的首屏性能飞跃。按照“评估依赖 ➔ 精简配置 ➔ 重构 Outlet 路由 ➔ 对齐 app 运行时 ➔ 验证排障”的标准化路径推进，中大型业务项目即可稳健、高效地完成架构现代化升级。