UmiJS 4.0 升级指南：从 Umi 3 平滑迁移到 Umi 4

UmiJS 4.0 升级指南：从 Umi 3 平滑迁移到 Umi 4

前言

UmiJS 作为企业级前端应用框架，在 4.0 版本中带来了诸多重大改进。本文将详细介绍如何将现有项目从 Umi 3 升级到 Umi 4，帮助开发者顺利完成迁移工作。

升级准备工作

在开始升级前，建议：

1. 确保项目当前在 Umi 3 下运行正常
2. 备份重要代码和配置文件
3. 了解 Umi 4 的主要变更点

详细升级步骤

第一步：依赖管理升级

Umi 4 对核心依赖进行了重构，首先需要更新 package.json：

{
  "devDependencies": {
+   "@umijs/max": "^4.0.0",
-   "umi": "^3.0.0",
-   "@umijs/preset-react": "^1.2.2"
  }
}

执行以下命令完成依赖更新：

rm -rf node_modules package-lock.json
npm install

第二步：脚本命令调整

Umi 4 引入了新的命令体系，需要更新 package.json 中的 scripts：

{
  "scripts": {
-    "build": "umi build",
+    "build": "max build",
-    "postinstall": "umi g tmp",
+    "postinstall": "max setup",
-    "start": "umi dev",
+    "start": "max dev",
  }
}

第三步：处理第三方插件

Umi 4 对插件系统进行了重构，建议：

1. 暂时注释掉非官方插件
2. 移除以下前缀的依赖：
   • umi-plugin-
   • @umijs/plugin-
   • @umijs/preset-

第四步：配置迁移

Umi 4 的配置更加显式，以下是典型配置示例：

import { defineConfig } from 'umi';

export default defineConfig({
  model: {},
  antd: {},
  request: {},
  initialState: {},
  mock: {
    include: ['src/pages/**/_mock.ts'],
  },
  dva: {},
  locale: {
    default: 'zh-CN',
    antd: true,
    baseNavigator: true,
  },
  fastRefresh: true,
});

主要变更点：

• fastRefresh 改为布尔值
• 移除了 dva.hmr 配置
• 默认使用 webpack5，无需显式配置

第五步：代码适配

路由系统升级

Umi 4 使用 react-router@6，主要变更：

1. 子路由渲染：

import { Outlet } from 'umi';
function Layout() {
  return (
    <div>
-     {props.children}
+     <Outlet />
    </div>
  );
}

2. 路由参数传递：

function Parent() {
  return (
-   <>{React.cloneElement(props.children, { someProp: 'value' })}</>
+   <Outlet context={{ someProp: 'value' }} />
  );
}

function Child() {
- const { someProp } = props;
+ const { someProp } = useOutletContext();
}

常用API变更

1. history 使用：

+ import { history } from 'umi';
function Page() {
  return (
    <button onClick={() => {
-     props.history.push('/list');
+     history.push('/list');
    }} />
  );
}

2. location 获取：

+ import { useLocation } from 'umi';
function Page() {
+ const location = useLocation();
  return (
    <div>
-     {props.location.pathname}
+     {location.pathname}
    </div>
  );
}

3. match 使用：

+ import { useMatch } from 'umi';
function Page() {
+ const match = useMatch('/users/:id');
  return (
    <div>
-     {props.match.params.id}
+     {match.params.id}
    </div>
  );
}

常见问题解决

1. location.query 不可用

Umi 4 移除了 location.query，推荐使用 URLSearchParams：

import { parse } from 'query-string';
const query = parse(location.search);

2. 类型定义文件引用问题

Umi 4 对类型引用更加严格：

- import { ButtonProps } from './button';
+ import type { ButtonProps } from './button.d';

3. 样式文件加载顺序

如果遇到样式覆盖问题，可以尝试：

export default defineConfig({
  styles: [
    // 确保antd样式优先加载
    'antd/dist/antd.css',
    // 项目样式后加载
    '@/styles/global.less',
  ],
});

升级后验证

完成升级后，建议：

1. 运行 max dev 启动开发服务器
2. 全面测试各功能模块
3. 检查控制台是否有警告或错误
4. 验证生产构建 max build

总结

Umi 4 带来了诸多改进，虽然升级过程需要一些适配工作，但新版本在性能、可维护性和开发体验上都有显著提升。按照本文指南逐步操作，可以顺利完成项目升级。如果在升级过程中遇到特殊问题，建议查阅 Umi 4 的官方文档获取更多细节信息。