快速上手企业级前端开发：深入理解 UMI 框架

UMI是蚂蚁金服的底层前端框架，也是一个基于React的企业级前端应用框架，它提供了开箱即用的项目脚手架和插件化的配置，如路由构建、部署测试、文档工具、请求库等，帮助开发者快速搭建和管理复杂的前端项目，其设计目标是提高前端项目的开发效率和可维护性，尤其适用于大型复杂项目的开发与管理。

初识UMI

    我们以前在使用react脚手架开发项目时要经过一些大量的配置，如果我们需要数据交互的话需要安装数据交互的请求库，如果需要状态管理则需要安装一些第三方的状态管理，当需要用到UI组件布局时则需要自行安装加配置一些移动端和PC端的一些组件库，当需要进行路由跳转时则需要安装一些第三方的路由插件等等，需要做一些大量的配置方面的东西。

    今天讲解的UMI，中文发音为「**乌米**」则是将这些常用的技术栈进行一个收纳，也就是当我们安装UMI之后这些配置以及默认帮我们装好且做了一些默认的配置，由此可以省下我们的精力专注于业务开发，这里我们查阅一下 官方文档 ，可以看到目前的UMI已经迭代到4.3.6版本了(博主当时最新)，如下图所示：

    学习UMI的话分两块学习，一种就是单纯的umi.js正常项目开发；另一种就是umi max(ant design pro) 也就是设计体系的企业级中后台前端/设计解决方案。两者都会讲解到，今天我们先讲解一下前者的开发。

    接下来我们就尝试一下使用umi这个框架进行开发项目吧，官方文档推荐我们使用pnpm，好吧那我们就使用pnpm进行搭建umi框架，没有pnpm的先全局安装一下 npm i -g pnpm 这里不再赘述，按钮命令如下：

pnpm dlx create-umi@latest

执行安装命令填写完项目名称之后，然后就进入到选择umi模板的选项，四个选项很简单，如下：

Simple App：默认安装模板，采用react

Ant Design Pro：需要进行 Umi Max 开发的模板

Vue Simple App：采用vue语法的模板

Umi Plugin：采用Umi插件的模板

这里我们就默认选择第一个 Simple App 模板进行讲解吧：

接下来进入到要选择什么包管理工具，人家推荐 pnpm 的话就选择这个吧：

接下来进入到要选择什么镜像源，这里选择国内的淘宝镜像即可，选择完成之后等待一段时间安装即可：

安装完成之后，回到我们的编辑器，终端执行 pnpm run dev 命令即可运行项目：

当然这里我们也可以安装一些常用的第三方库，以备后面的项目使用到：

pnpm i antd qs styled-components @umijs/plugins

目录分析

UMI官方罗列了项目中约定(或推荐)的目录结构，在项目开发中请遵照这个目录结构组织代码，项目的结构如下所示，好吧对于我个人来讲有点不习惯，但是还是按照官方文档的来吧。

.
├── config
│   └── config.ts
├── dist
├── mock
│   └── app.ts｜tsx
├── src
│   ├── .umi
│   ├── .umi-production
│   ├── layouts
│   │   ├── BasicLayout.tsx
│   │   ├── index.less
│   ├── models
│   │   ├── global.ts
│   │   └── index.ts
│   ├── pages
│   │   ├── index.less
│   │   └── index.tsx
│   ├── utils // 推荐目录
│   │   └── index.ts
│   ├── services // 推荐目录
│   │   └── api.ts
│   ├── app.(ts|tsx)
│   ├── global.ts
│   ├── global.(css|less|sass|scss)
│   ├── overrides.(css|less|sass|scss)
│   ├── favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)
│   └── loading.(tsx|jsx)
├── node_modules
│   └── .cache
│       ├── bundler-webpack
│       ├── mfsu
│       └── mfsu-deps
├── .env
├── plugin.ts 
├── .umirc.ts // 与 config/config 文件 2 选一
├── package.json
├── tsconfig.json
└── typings.d.ts

接下来着重讲解一下上面目录结构中重要的文件配置，如下：

.env：配置环境变量，默认基础模板是没有这个文件的，需要手动在根目录下创建，环境变量如下所示，可以看到外面配置的环境变量起到作用了：

当然除了.env文件中可以设置环境变量之外，还可以使用 cross-env 设置环境变量，这里我们需要终端执行如下命令安装这个工具：

pnpm install cross-env -D

然后在package.json文件中，设置如下命令进行环境变量配置，当然如果你已经设置过.env文件的话，优先级还是以**.env**文件为主：

"scripts": {
  "dev": "umi dev",
  "build": "umi build",
  "postinstall": "umi setup",
  "setup": "umi setup",
  "start": "cross-env PORT=3333 HOST=127.0.0.1 umi dev"
},

不过相对来说，使用 cross-env 进行环境变量配置更加灵活，这里我们可以设置不同的情况：

"start": "cross-env PORT=9933 MOCK=none max dev",  
"start:dev": "cross-env PORT=9933 REACT_APP_ENV=dev MOCK=none UMI_ENV=dev max dev",  
"start:mock": "cross-env PORT=9933 npm run dev",  
"start:pro": "cross-env PORT=9933 UMI_ENV=pro MOCK=none max dev",  
"start:prorelease": "cross-env PORT=9933 UMI_ENV=prorelease MOCK=none max dev",  
"start:release": "cross-env PORT=9933 UMI_ENV=release MOCK=none max dev",  
"start:test": "cross-env PORT=9933 REACT_APP_ENV=test MOCK=none UMI_ENV=test max dev",  

.umirc.ts：该文件是对webpack进行配置的，配置的都是非运行配置(webpack配置)：

config/config.ts：config/config.ts也可以对webpack进行配置，如果和.umirc.ts和其两个文件都存在且对同一功能进行不同配置，.umirc.ts文件的优先级更高：

app.ts：运行配置一般都是放在app.ts中，可以在这里扩展运行时的能力，比如修改路由、修改 render 方法等，其带来的逻辑会在浏览器中运行，因此当有远程配置、动态内容时，这些我们在本地开发时还不确定，不能写死，所以需要在浏览器实际运行项目时动态获取他们：

.umi：dev时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。

.umi-production：build时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。

layouts/index.tsx：umi会根据路由进行匹配，匹配到的组件都会放到Outlet中渲染，类似如下：

/ ===> index.tsx组件 放到 Outlet中渲染

/docs ===> docs.tsx组件 放到 Outlet中渲染

pages：放在pages文件下的组件会自动生成路由，也就是说不需要我们再配置路由了，这种路由我们叫做约定式路由。

比如我们随便在pages文件下创建一个tsx文件，都不用配置路由直接生效了：

global.tsx：umi区别于其他前端框架，没有显式的程序主入口（如 src/index.ts），所以当你有需要在应用前置、全局运行的逻辑时，优先考虑写入 global.ts，也就是说我们可以将其当作是一个入口文件，当然还有global.less全局样式文件。

loading.tsx：全局加载组件UMI4默认按页分包 ，从而在页面切换时存在加载过程，通过该文件来配置加载动画：

plugin.ts：项目级UMI插件，当有定制需求时，往往会用到插件 API （比如 修改产物 html），此时可创建该文件进行自定义。

favicon：站点favicon图标文件，当存在src/favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)文件时，将会自动在产物中添加站点favicon。

当然还有一些其他常见的文件，这里就简单的赘述一下：

dist：执行umi build后产物的默认输出文件夹，可通过outputPath配置修改产物输出文件夹

mock：存放mock文件，此目录下所有 .ts / .js 文件会被 mock 服务加载，从而提供模拟数据

public：存放固定的静态资源，如存放 public/image.png ，构建后会被拷贝到输出文件夹

UMI项目配置

对于 umi 中能使用的自定义配置，可以使用项目根目录的 .umirc.ts 文件或者 config/config.ts，这两个文件功能一致，仅仅是存在目录不同，2 选 1 ，.umirc.ts 文件优先级较高。

配置别名：在config下文件下的config.ts中配置，或者在.umirc.ts中，配置别名的时候应采用如下方式配置：

const resolve = (dir) => require('path').join(__dirname, dir);
 
export default defineConfig({
    ...其他配置
    alias: {
    '@': resolve('/src'),
    '@p': resolve('/src/pages'),
    '@c': resolve('/src/components'),
  },
})

配置sourceMap：运行起来的项目，是经过webpack打包后的代码，webpack把源码打包后，放到的内存服务器。运行起来的代码是内存服务器中的代码，并不是源码。报的错误是内存服务器中代码的错误，并不是源码中的错误。要找到是源码中哪个地方出错，需要通过sourceMap，默认在dev环境下，开启了souceMap：

// 关闭 dev 阶段的 sourcemap 生成
devtool: false;

// 只设置 dev 阶段的 sourcemap
devtool: process.env.NODE_ENV === 'development' ? 'eval' : false;

添加hash：配置hash，打包后资源会加上hash，如下：

图片转base64：设置图片转base64，方式如下：

设置JS的压缩方式：配置构建时压缩 JavaScript 的工具，具体可以参考官网：

设置UMI插件：数组项为指向插件的路径，可以是 npm 依赖、相对路径或绝对路径。如果是相对路径，则会从项目根目录开始找：

设置资源打包路径： 项目部署时，如果直接部署到服务器的根路径，是没有问题，如果部署时，资源没有放到根下面，比如放到/abc/下面了就找不到了。此时，可以配置打包后资源导入路径，默认也是/，如下：

配置title：配置网站的标题的话可以采用下面的方式进行：

proxy：配置代理功能

proxy: {
  '/api': {
    'target': 'http://jsonplaceholder.typicode.com/',
    'changeOrigin': true,
    'pathRewrite': { '^/api' : '' },
  }
}

当然还有一些其他的配置，这里就不再一一赘述，可自行去官网查看！