2025 年 umi 🆚 umi max

背景

umijs v4 后出现了 umi 和 max。如果升级或二者之间选型应该如何选。

本文将试图从代码层面比较二者，让大家对二者有个清晰的认识。

文章代码基于 @umijs/max v4.4.9 umi v4.4.9 本文日期 2025-4-23。

TLDR

max = umi + 一系列预制插件（antd、权限、数据流、微前端、tailwindcss…… 可按需启用）

如果你是想做一个基于 antd 的复杂中后台项目（集成权限、微前端），推荐 umi max，否则 umi。

区别

一、依赖

max 本身依赖

"antd": "^4.20.6",
"eslint": "8.35.0",
"stylelint": "14.8.2",
"@umijs/lint": "4.4.9",
"@umijs/plugins": "4.4.9",
"umi": "4.4.9"

-_-|| antd 重复依赖了，脚手架生成的项目依赖的是 antd v5，但此处却是 v4。

可见 max 底层依赖 umi，但预置了各种插件：

export default () => {
  return {
    plugins: [
      require.resolve('@umijs/plugins/dist/access'),
      require.resolve('@umijs/plugins/dist/analytics'),
      require.resolve('@umijs/plugins/dist/antd'),
      require.resolve('@umijs/plugins/dist/dva'),
      require.resolve('@umijs/plugins/dist/initial-state'),
      require.resolve('@umijs/plugins/dist/layout'),
      require.resolve('@umijs/plugins/dist/locale'),
      require.resolve('@umijs/plugins/dist/mf'),
      require.resolve('@umijs/plugins/dist/model'),
      require.resolve('@umijs/plugins/dist/moment2dayjs'),
      require.resolve('@umijs/plugins/dist/qiankun'),
      require.resolve('@umijs/plugins/dist/react-query'),
      require.resolve('@umijs/plugins/dist/request'),
      require.resolve('@umijs/plugins/dist/styled-components'), 
      require.resolve('@umijs/plugins/dist/tailwindcss'),
      require.resolve('@umijs/plugins/dist/valtio'),
      require.resolve('./plugins/maxAlias'),
      require.resolve('./plugins/maxAppData'),
      require.resolve('./plugins/maxChecker'),
    ],
  };
};

上述几乎都在文档有体现比如 access 权限插件，文档：umijs.org/docs/max/ac… 。挑几个重点或不认识的看看。

• dva 基于 redux effect yield put 等概念太多，“上世纪”的产物，不推荐，推荐 valtio 或者 zustand（非 umi 项目） 。
• mf ModuleFederation。
• model 数据流 umijs.org/docs/max/da… 推荐 valtio。
• valtio 蚂蚁内部 bigfish 使用的状态管理，基于 proxy umijs.org/docs/max/va…
• maxAlias 别名 @umijs/max => @@/exports。
• maxAppData 将 name 改成 Umi Max。开发者无需关心。
• maxChecker 检查 max 项目 package.json 是否有依赖 umi 有则报错提示。

// maxAlias
import { IApi } from 'umi';

export default (api: IApi) => {
  api.modifyConfig((memo) => {
    memo.alias = {
      ...memo.alias,
      '@umijs/max': '@@/exports',
    };
    return memo;
  });
};

脚手架生成的项目依赖

umi 改成 @umi/max，新增了 antd 全家桶

"@umijs/max": "^4.4.9",

"@ant-design/icons": "^5.0.1",
"@ant-design/pro-components": "^2.4.4",
"antd": "^5.4.0"

二、目录结构

Windows 自带 tree 非常难用，找到一个高质量的 tree 替代品

pnpm i -g tree-node-cli

❯ tree my-app -I 'node_modules'
my-app
├── package.json
├── pnpm-lock.yaml
├── src
│   ├── assets
│   │   └── yay.jpg
│   ├── layouts
│   │   ├── index.less
│   │   └── index.tsx
│   └── pages
│       ├── docs.tsx
│       └── index.tsx
├── tsconfig.json
└── typings.d.ts

❯ tree my-app-max -I 'node_modules'
my-app-max
├── README.md
├── mock
│   └── userAPI.ts
├── package.json
├── pnpm-lock.yaml
├── src
│   ├── access.ts
│   ├── app.ts
│   ├── assets
│   ├── components
│   │   └── Guide
│   │       ├── Guide.less
│   │       ├── Guide.tsx
│   │       └── index.ts
│   ├── constants
│   │   └── index.ts
│   ├── models
│   │   └── global.ts
│   ├── pages
│   │   ├── Access
│   │   │   └── index.tsx
│   │   ├── Home
│   │   │   ├── index.less
│   │   │   └── index.tsx
│   │   └── Table
│   │       ├── components
│   │       │   ├── CreateForm.tsx
│   │       │   └── UpdateForm.tsx
│   │       └── index.tsx
│   ├── services
│   │   └── demo
│   │       ├── UserController.ts
│   │       ├── index.ts
│   │       └── typings.d.ts
│   └── utils
│       └── format.ts
├── tsconfig.json
└── typings.d.ts

对比

删除了 layout 目录（估计是内置了 antd pro 的 layout）、新增了 components constants models services utils 比较感兴趣的是 models services

// my-app-max/src/models/global.ts

// 全局共享数据示例
import { DEFAULT_NAME } from '@/constants';
import { useState } from 'react';

const useUser = () => {
  const [name, setName] = useState<string>(DEFAULT_NAME);
  return {
    name,
    setName,
  };
};

export default useUser;

自动生成

❯ cat my-app-max/src/services/demo/UserController.ts
/* eslint-disable */
// 该文件由 OneAPI 自动生成，请勿手动修改！
import { request } from '@umijs/max';

/** 此处后端没有提供注释 GET /api/v1/queryUserList */
export async function queryUserList(
  params: {
    // query
    /** keyword */
    keyword?: string;
    /** current */
    current?: number;
    /** pageSize */
    pageSize?: number;
  },
  options?: { [key: string]: any },
) {
  return request<API.Result_PageInfo_UserInfo__>('/api/v1/queryUserList', {
    method: 'GET',
    params: {
      ...params,
    },
    ...(options || {}),
  });
}

...

三、脚手架生成项目对比

umi

选择 Simple App。

❯ pnpx create-umi@latest
Packages: +39
+++++++++++++++++++++++++++++++++++++++
Progress: resolved 40, reused 10, downloaded 29, added 39, done
┌   create-umi
│
○  What's the target folder name?
│  my-app
│
○  Pick Umi App Template
│  Simple App
│
○  Pick Npm Client
│  pnpm
│
○  Pick Npm Registry
│  taobao
│
└  You're all set!

 WARN  deprecated eslint@8.57.1: This version is no longer supported. Please see https://eslint.org/version-support for other opti
ons.loading @umijs/mako-win32-x64-msvc@0.11.10: 15.68 MB/16.66 MB
Downloading @umijs/mako-win32-x64-msvc@0.11.10: 16.66 MB/16.66 MB, done
 WARN  12 deprecated subdependencies found: @esbuild-kit/cjs-loader@2.4.4, @esbuild-kit/core-utils@3.3.2, @esbuild-kit/esm-loader@
2.6.5, @floating-ui/react-dom-interactions@0.3.1, @humanwhocodes/config-array@0.13.0, @humanwhocodes/object-schema@2.0.3, @styleli
nt/postcss-css-in-js@0.38.0, glob@7.2.3, inflight@1.0.6, node-domexception@1.0.0, rimraf@3.0.2, stable@0.1.8
Packages: +1034
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 1115, reused 106, downloaded 927, added 1034, done

> @ postinstall F:\temp\my-app
> umi setup

info  - [你知道吗？] umi g tsconfig 可一键完成项目的 TypeScript 配置。
info  - generate files
info  - Preparing...

dependencies:
+ umi 4.4.9

devDependencies:
+ @types/react 18.3.20 (19.1.2 is available)
+ @types/react-dom 18.3.6 (19.1.2 is available)
+ typescript 5.8.3

╭ Warning ───────────────────────────────────────────────────────────────────────────────────╮
│                                                                                            │
│   Ignored build scripts: core-js, core-js-pure, esbuild.                                   │
│   Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.   │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Done in 1m 29.4s
\
 F:\temp via Node.js v22.7.0 took 2m5s

umi max

选择 Ant Design Pro。

❯ pnpx create-umi@latest
┌   create-umi
│
○  What's the target folder name?
│  my-app-max
│
○  Pick Umi App Template
│  Ant Design Pro
│
○  Pick Npm Client
│  pnpm
│
○  Pick Npm Registry
│  taobao
│
└  You're all set!

Downloading antd@5.24.8: 10.19 MB/10.19 MB, done
Downloading antd@4.24.16: 8.75 MB/8.75 MB, done
Downloading @formatjs/intl-displaynames@1.2.10: 5.85 MB/5.85 MB, done
 WARN  19 deprecated subdependencies found: @esbuild-kit/cjs-loader@2.4.4, @esbuild-kit/core-utils@3.3.2, @esbuild-kit/esm-loader@
2.6.5, @floating-ui/react-dom-interactions@0.3.1, @formatjs/intl-unified-numberformat@3.3.7, @formatjs/intl-utils@2.3.0, @humanwho
codes/config-array@0.11.14, @humanwhocodes/object-schema@2.0.3, @stylelint/postcss-css-in-js@0.38.0, @types/history@5.0.0, eslint@
8.35.0, flatten@1.0.3, glob@7.2.3, inflight@1.0.6, intl-messageformat-parser@3.6.4, node-domexception@1.0.0, react-router-redux@5.
0.0-alpha.9, rimraf@3.0.2, stable@0.1.8
Packages: +1329
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Downloading @formatjs/intl-unified-numberformat@3.3.7: 8.47 MB/8.47 MB, done
Progress: resolved 1399, reused 1027, downloaded 290, added 1329, done

> @ postinstall F:\temp\my-app-max
> max setup

info  - [你知道吗？] 你知道可以通过 UMI_ENV 定义多个环境的配置吗，详见 https://umijs.org/docs/guides/env-variables#umi_env
info  - generate files
info  - Preparing...

> @ prepare F:\temp\my-app-max
> husky

 WARN  Issues with peer dependencies found
.
├─┬ dva 2.5.0-beta.2
│ ├── ✕ unmet peer react@"15.x || ^16.0.0-0": found 18.3.1
│ ├── ✕ unmet peer react-dom@"15.x || ^16.0.0-0": found 18.3.1
│ └─┬ react-redux 5.1.2
│   └── ✕ unmet peer react@"^0.14.0 || ^15.0.0-0 || ^16.0.0-0": found 18.3.1
└─┬ @umijs/max 4.4.9
  └─┬ @umijs/plugins 4.4.9
    ├─┬ @ahooksjs/use-request 2.8.15
    │ └── ✕ unmet peer react@"^16.8.0 || ^17.0.0": found 18.3.1
    ├─┬ react-intl 3.12.1
    │ └── ✕ unmet peer react@^16.3.0: found 18.3.1
    └─┬ dva-loading 3.0.25
      └── ✕ unmet peer dva-core@"^1.1.0 || ^1.5.0-0 || ^1.6.0-0": found 2.0.4

dependencies:
+ @ant-design/icons 5.6.1 (6.0.0 is available)
+ @ant-design/pro-components 2.8.7
+ @umijs/max 4.4.9
+ antd 5.24.8

devDependencies:
+ @types/react 18.3.20 (19.1.2 is available)
+ @types/react-dom 18.3.6 (19.1.2 is available)
+ husky 9.1.7
+ lint-staged 13.3.0 (15.5.1 is available)
+ prettier 2.8.8 (3.5.3 is available)
+ prettier-plugin-organize-imports 3.2.4 (4.1.0 is available)
+ prettier-plugin-packagejson 2.5.10
+ typescript 5.8.3

╭ Warning ───────────────────────────────────────────────────────────────────────────────────╮
│                                                                                            │
│   Ignored build scripts: core-js, core-js-pure, es5-ext, esbuild.                          │
│   Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.   │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Done in 2m 49.9s
\
 F:\temp via Node.js v22.7.0 took 3m22s