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 umilatest执行后命令行会问你几个问题包括项目名称、选择哪种模板基础模板还是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这个hookumi封装的路由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.tsexport default { GET /api/users: { code: 0, data: [/* 一份模拟用户数据 */] }, };本地开发时umi会自动拦截匹配的路由返回伪造数据。等后端接口真正可用之后删掉mock文件或者切换请求地址就能无缝过渡到真实接口。这里有个细节值得注意Mock默认只在dev环境生效生产构建时不会打包进去不用担心污染线上代码。我在多个项目里都靠这招保证了前端先行开发的节奏。5.3 多环境变量管理中后台项目通常有dev、test、uat、prod几个环境每个环境的接口域名都不同。umi支持通过.env文件和环境变量來管理差异化配置。比如你可以在.env.test里写API_HOSThttps://test-api.example.com然后在配置里用process.env.API_HOST读取构建时通过UMI_ENVtest指定当前环境。这个小机制避免了在多套代码里手动替换接口地址是上线前最实用的省力技巧之一。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。相信我这个初探过程会比你预期的更加顺手。
