1. 为什么是umi：一次选型思考
1.1 React应用开发的“标配”痛点
先说个我自己的经历。有段时间我负责一个中后台管理系统，技术栈是React + Webpack + React Router + Redux，项目刚起步时一切还好，但随着页面越来越多，问题开始扎堆出现：路由配置和布局文件散落各处，权限逻辑要靠手写高阶组件到处套，环境变量和代理配置每个环境都得手工改一遍，最头疼的是新成员加入后光看项目结构就要小半天。那会儿我就在想，React本身只解决视图层的问题，剩下的工程化、约定、规范，其实都需要一个框架级别的方案来兜底。
后来我接触到umi，第一反应是“这不就是个React的脚手架吗”，但随着深入使用，我发现它远不止脚手架那么简单。你可以把umi理解成一套“覆盖全生命周期的React应用开发框架”，它的设计思路很直白：把React社区里那些零散的最佳实践固化下来，用约定代替配置，用插件机制补齐能力，让开发者把精力花在业务逻辑上，而不是天天跟构建配置死磕。对于中后台管理系统、办公协同工具、数据可视化平台这类项目，umi确实是一个相当“顺手”的起点。
1.2 umi给出的解法是什么
如果你去看umi的官方文档，会看到一句话叫“插件化的企业级前端应用框架”。这句话信息量很大。传统方案里，我们通常把路由、状态管理、UI库、请求库一个个手工接入，而umi把这一套东西全部打理好，并且保留了很强的扩展性。
它解决的核心问题有三个：
- 约定优于配置。页面的路由、布局、数据加载规则，都有清晰的文件系统约定。你只要按照目录结构放文件，路由就自动生成，不用再维护一份堆满路径映射的手写路由表。
- 能力内聚。路由、构建、部署、Mock、代理、权限、国际化、数据流，这些中后台项目里高频出现的需求，umi都提供了开箱即用的解决方案，不用到处找第三方库拼拼凑凑。
- 工程化底座一致。不管你是两个人写demo还是二十个人写大型项目，umi统一的目录结构、构建流程和规范，会让协作成本显著下降。新人上手时，照着约定放置项目文件，就能快速进入状态。
1.3 哪些场景更适合用umi
虽然umi很强大，但也不是万能的。我个人经验是，如果你做的是以下几类项目，umi的收益会特别明显：
- 中后台管理系统、Admin后台、运营平台，这类项目页面结构规律、交互密集，umi的路由约定和Layout布局能省下大量重复工作。
- 需要多环境部署和频繁联调的前端项目，umi的环境变量、代理转发和Mock能力很实用。
- 团队协作的多人项目，统一的工程约定和代码结构能显著降低沟通成本。
- 想快速验证产品原型，但又希望后续能平滑扩展成正式项目。
如果只是做一个简单的静态展示页，或者对包体积和自由度要求极高的特殊场景，那可能不需要上umi，直接用原生React或者Vite会更轻量。但放在大多数商业项目背景下，umi的优势还是很扎实的。
2. 环境准备与首个umi项目
2.1 前置环境要求
开始之前，先确认本地的Node环境。umi当前主要支持Node 18及以上版本，建议直接用LTS版本。如果还在用Node 14或者更早的版本，运行时会碰到一些兼容性报错，比如语法不支持、依赖安装失败之类的问题。
包管理器方面，npm、yarn、pnpm都能用，但我个人更推荐pnpm。原因很简单：安装速度快，磁盘占用少，最重要的是严格依赖管理可以避免不少“我本机跑得好好的，一到同事机器就报错”的诡异问题。如果你用pnpm，建议开启全局的pnpm store，这样多个项目复用依赖缓存，体验会好很多。
2.2 脚手架初始化
umi官方提供了一个叫create-umi的脚手架工具，初始化项目的命令非常简单：
pnpm create umi@latest执行后，命令行会问你几个问题，包括项目名称、选择哪种模板（基础模板还是Ant Design Pro模板）、是否开启TypeScript等。我的建议是，新手第一次接触umi时，直接选基础模板，不要一上来就套Ant Design Pro那个全家桶，因为Pro模板包含了大量业务模块和示例代码，结构复杂，不利于理解umi本身的约定。
生成完项目之后，进入目录安装依赖并启动开发服务：
cd my-umi-app pnpm install pnpm dev默认情况下，开发服务会跑在http://localhost:8000，浏览器打开就能看到一个Welcome页面。看到这个页面，说明umi骨架已经跑通了。
2.3 目录结构解读
刚初始化的项目目录结构看起来不复杂，但其中的约定你要看明白：
my-umi-app ├── package.json ├── .umirc.ts # umi的配置文件 ├── src │ ├── layouts # 全局布局目录 │ ├── pages # 页面目录，路由从这里生成 │ ├── app.tsx # 应用运行时的配置文件 │ └── models # 数据流模型目录 └── public # 静态资源目录这里最核心的就是src/pages目录。umi的约定式路由逻辑很简单：pages目录下的每个文件就是一个页面组件，文件路径就是路由路径。比如src/pages/index.tsx对应/，src/pages/user/list.tsx对应/user/list。
layouts/index.tsx是全局布局文件。你可以在里面写侧边栏、顶部导航、面包屑这些公共结构，umi会自动把页面内容渲染到布局的<Outlet />位置，相当于所有页面共享一套固定的外层框架。这个机制对中后台项目非常友好。
app.tsx则是应用运行时配置，比如全局的初始化逻辑、权限校验、请求配置，都可以在这里处理。我习惯把一些跟业务入口有关的东西放在这里，而不是写在组件内部。
一开始你可能不习惯这种“约定优于配置”的方式，会觉得“我没写路由注册代码，它怎么就知道去哪找页面？”但跑两个页面之后你就会发现，确实省事，而且团队里每个人理解的路由结构都是一致的，不用再靠口口相传。
3. 路由系统：umi的核心亮点
3.1 约定式路由的约定规则
umi的路由设计我认为是整个框架里最值得深挖的部分。它同时支持约定式路由和配置式路由，日常开发中我推荐直接用约定式，因为它跟目录结构的耦合天然一致，维护成本最低。
规则很简单：
src/pages/index.tsx->/src/pages/user/index.tsx->/usersrc/pages/user/list.tsx->/user/listsrc/pages/user/detail/[id].tsx->/user/detail/:idsrc/pages/user/detail/index.tsx->/user/detail
动态路由用方括号语法，比如post/[id].tsx就对应/post/123这种链接。页面组件访问动态参数时，可以用useParams这个hook，umi封装的路由hooks跟React Router的用法一脉相承，熟悉React Router的人几乎零学习成本。
还有一点很多人容易忽略：404页面。在pages目录下创建一个404.tsx文件，umi会自动把它作为路由找不到时的兜底页面。这个机制非常省心，不用再到路由表里单独配置通配符。
3.2 嵌套路由与布局
在实际项目中，只有全局布局往往不够。比如用户管理模块下面有列表页和详情页，这两个页面除了全局侧边栏，还需要一套“模块内公共布局”，比如局部Tabs或者步骤条。
umi的解决方式是使用_layout.tsx文件。在pages/user/目录下建一个_layout.tsx，它就会自动成为/user这个路由下的局部布局，渲染到全局布局的内容区域里，然后像套娃一样再渲染子页面组件。
这种层层嵌套的布局方式，跟物理目录结构完全对应，对多人协作非常友好。你要知道“这个模块的布局结构是什么样的”，直接看目录树就清楚了。
3.3 动态路由与权限控制
动态路由在很多系统里是核心需求——不同角色的人看到的菜单和页面不一样。umi可以通过配置式路由配合运行时权限来实现，也可以在约定式路由的基础上，结合access插件和app.tsx里的初始化逻辑做控制。
我的做法通常是：在app.tsx里登录成功后获取用户角色信息，通过access插件的canUse逻辑去控制路由的可见性和可访问性。菜单项能隐藏、按钮能禁用，页面也能拦截无权限访问的请求，整体联动非常顺手。
这里有一个实操经验：动态权限的粒度不要做得太细，否则后期迭代的时候会非常痛苦。把权限控制在“页面”和“按钮”这两层，是我踩过坑之后的真实建议。
4. 配置与插件机制
4.1 配置文件的核心配置项
umi的配置文件是根目录下的.umirc.ts（环境差异化配置可以用config/config.ts），这里面可以定义几乎所有项目级别的选项。挑几个高频使用的配置项说说：
export default { base: '/admin/', // 路由基础路径 publicPath: '/static/', // 静态资源公共路径 hash: true, // 打包文件名带hash proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true, }, }, fastRefresh: true, // 快速热更新 mfsu: {}, // 模块联邦级加速 };base和publicPath通常配合部署场景使用。比如站点要挂在域名下的/admin路径，就需要设置base: '/admin/'，同时后端反向代理要把对应前缀转发到前端服务。很多部署后白屏的问题，八成都是这两个配置没配对。
proxy是联调利器。本地开发时，后端接口跑在另一台机器或者另一个端口，通过代理配置就能把/api开头的请求转发到目标地址，避免浏览器的跨域限制。这个配置只影响开发环境，生产环境不需要。
fastRefresh和mfsu都是提升开发体验的。前者让你保存代码后组件的状态尽量不丢失，后者通过模块联邦的缓存机制大幅缩短冷启动和热更新的时间。大项目中这两个配置可以说是刚需。
4.2 常用插件怎么选
umi的插件机制非常强大，可以说“一切能力皆插件”。即便你只装了基础的@umijs/preset-umi，也自带了一套核心能力。需要更多功能时，可以按需安装插件。
日常项目中我用到最多的几个：
@umijs/plugins内置了access（权限）、layout（布局）、locale（国际化）、request（请求）等能力，开启后直接在配置里声明即可。@umijs/max是基于umi封装的一套增强方案，适合开箱就想要齐全套中后台能力的团队。- 第三方生态里还有大量插件，比如跟Ant Design的深度集成、TailwindCSS的支持、代码生成器等等，在npm上搜索
umi-plugin-前缀就能发现不少。
插件系统的意义在于：umi的团队不会什么都硬塞进核心，而是把能力边界划分清楚，你要什么就装什么，避免项目里堆积无用依赖。
4.3 微前端等高级特性的延展
在小团队里可能用不上，但如果你所在的公司有多个前端团队各自维护一套系统，后来想整合成一个大的工作台，微前端就派上用场了。umi官方推出了基于qiankun的微前端方案，在umi项目里接入非常平滑。
具体来说，一个项目可以充当主应用，通过配置注册其他umi子应用的地址，子应用也可以独立开发、独立部署。这套方案的价值在于：技术栈异构的项目也能共用一个外壳，团队之间不必从零开始合并代码。
我处理过一个把Excel处理、报表展示、审批流三个不同时期开发的应用合到一个入口的项目，主应用只负责登录、导航和菜单聚合，子应用各自保留业务逻辑。整体平滑度比预期好很多，这个能力是umi在大型组织复杂度下很值得称道的部分。
5. 数据请求与Mock联调
5.1 request封装与统一错误处理
前端项目的接口请求能力，如果从零开始封装，要处理超时、鉴权、拦截、错误码统一解析等一系列问题。umi里可以直接用@umijs/max里的request，或者单独安装@umijs/request。
基本用法：
import { request } from 'umi'; const users = await request('/api/users', { method: 'POST', data: { page: 1 }, });更重要的其实是统一的拦截器。在src/app.tsx里，可以配置请求和响应的拦截逻辑，我通常会在这里做三件事：
- 请求前自动带上登录token。
- 响应后统一判断HTTP状态码和业务状态码，非200的情况弹出统一错误提示。
- 遇到401时，自动跳转登录页并清理本地用户信息。
这样业务代码里就不用每个请求都写一遍token和错误处理，页面代码会干净很多。
5.2 Mock数据与开发脱钩
前后端并行开发时，最怕的是等接口。“接口还没好”这种情况在中小团队尤其常见。umi内置的Mock功能可以把联调问题处理得很优雅。
在mock目录下创建一个users.ts：
export default { 'GET /api/users': { code: 0, data: [/* 一份模拟用户数据 */] }, };本地开发时，umi会自动拦截匹配的路由，返回伪造数据。等后端接口真正可用之后，删掉mock文件或者切换请求地址，就能无缝过渡到真实接口。
这里有个细节值得注意：Mock默认只在dev环境生效，生产构建时不会打包进去，不用担心污染线上代码。我在多个项目里都靠这招保证了前端先行开发的节奏。
5.3 多环境变量管理
中后台项目通常有dev、test、uat、prod几个环境，每个环境的接口域名都不同。umi支持通过.env文件和环境变量來管理差异化配置。
比如你可以在.env.test里写：
API_HOST=https://test-api.example.com然后在配置里用process.env.API_HOST读取，构建时通过UMI_ENV=test指定当前环境。这个小机制避免了在多套代码里手动替换接口地址，是上线前最实用的省力技巧之一。
6. 常见问题与排查技巧实录
6.1 访问页面404或者白屏
这个是我碰到最多的一个问题。窍门是先从路由匹配入手，确认访问路径跟pages目录里的文件对应。注意文件名的大小写以及[id]动态段的写法，一个拼写错误就会导致找不到页面。
如果路径正确但还是白屏，查看浏览器控制台的报错。绝大多数情况下是组件内部抛错，比如某个hook拿不到参数、某个接口返回空数据导致上层组件崩溃。建议先把页面组件里的逻辑拆成最小单元，逐步排查。
6.2 热更新失效或保存后页面不刷新
热更新失效通常有几种原因：项目的Node版本太低、某些非受控文件被编辑器改动、或者依赖版本冲突。最直接的解决方法是删掉node_modules和锁文件重新安装依赖，很多“玄学”热更新问题会自然消失。
另外，要让fastRefresh和mfsu发挥最大作用，最好把桌面端的浏览器代理、杀毒软件之类的干扰因素排除掉，有些局域网安全软件会拦截本地回环请求，导致WebSocket连接异常。
6.3 打包体积过大
构建产物体积大，绝大部分是因为依赖没有合理分包。umi的默认配置已经做了不少优化，但你还是可以手动控制：
- 使用动态路由加
React.lazy拆分大页面模块。 - 对Ant Design这类大型UI组件库按需引入。
- 把第三方库通过
splitchunks配置拆分成独立包，避免所有东西揉在一个文件里。 - 检查代码里是否有不小心全量引入的库，比如
lodash和moment，尽量使用按需引入版本或者换成更轻的替代库。
我接手的一个老项目就是把moment全量引入，仅仅为了用几个日期格式化函数，替换成轻量日期库后整个包体积直接减少了10%。这类问题在umi项目里也一样，审查依赖需要成为习惯。
7. 对umi的几点个人体会
从一个“随便看看”的框架，到真正把它用在中后台项目中，我的感受是：umi确实把一个大型React项目的核心工程问题，从“无政府状态”梳理成了“有规范的秩序”。它没有要求你必须接受某一种开发模式，而是提供了一个高度统一的工作台，让注意力重新回到业务本身。
我最欣赏的是它的文档质量和社区生态。中文文档写得相当清晰，插件机制说明到位，基本上遇到问题都能在官方文档和社区讨论里找到答案。对于团队而言，选umi基本等于选了一套长期有人维护的工程底座，这一点在项目进入维护期之后尤为重要。
如果你正在React的工程化选择上犹豫，或者中后台项目里反复摩擦路由、权限、请求这些环节，建议花一两天时间从umi的约定式路由开始，跑通一个带权限控制和数据请求的demo。相信我，这个初探过程会比你预期的更加顺手。
