『Umi』约定式路由 - 从安装到实践的完整指南

一、前言

🐤本篇文章是『从零玩转 TypeScript + React 项目实战』系列文章的第 10 篇，《约定式路由 - 从安装到实践的完整指南》

经过前面的学习，了解了下 Dva，了解完 Dva 之后，这篇文章开始，在给大家介绍一个 Umi 的东西。

二、Umi

2.1 什么是 Umi

• Umi 是蚂蚁金服的底层前端框架（经蚂蚁内部 3000+ 项目经验）有大量的项目都在使用 Umi。
• Umi 它是一个以 ‘路由’ 为基础的企业级 Recat 框架（为核心的框架，同时支持配置式理由和约定式路由）
• Umi 它是一个 ‘可插拔’ 的企业级 React 应用框架（内部功能完全使用插件化完成，来实现）

所以说：

• Umi 是一个蚂蚁金服底层的，以‘路由’为基础的，内部（核心）功能完全使用插件化完成的一个 Recat 框架。

所以说 Umi 呢它的核心呢就是 ‘理由’ 和 ‘插件’。

所以说，给大家介绍 Umi，就是介绍 Umi 的路由和插件，知道吧。

那么了解完了什么是 Umi，了解完了 Umi 的核心是什么东西，了解完了学 Umi 应该学什么之后，接下来是不是就要来动手了学习一下子了呢？好，本文章我就将继续带着给大家分享。

Umi 官方文档：https://v3.umijs.org/zh-CN

2.2 Umi 的安装与使用

进入到官方第一眼看到的就是对 Umi 的介绍，往下拖，就可以看到就告诉我们如何三分钟上手 Umi：

其实呢，上手 Umi 根本就用不了三分钟，一分钟就能上手，首先我们需要创建一个 NodeJS 项目：

mkdir myapp && cd myapp
npm init -y

然后再项目当中安装 Umi：

npm install umi --save

or

yarn add umi

安装 Umi 之后呢，Umi 就会给我们提供一些指令，我们就可以通过这些指令来创建界面：

创建好界面之后我们就可以运行 Umi 项目了。所以我这就进入到我项目进行操作操作操练起来：

在我项目的根目录下创建一个文件夹 demo 的 NodeJS 项目：

来到终端 cd 到 demo 目录下，然后执行 npm init -y 初始化一个 NodeJS 项目：

然后执行 npm install umi@3.2.24 --save 安装 Umi，在安装之前大家先确认一下自己的 NodeJS 版本，我这里使用的是 14.3.0 版本，因为高版本在安装 Umi 的时候会报错，新版本 Node.js 版本中不再支持 node-waf，我 umi 版本是 3.2.24，所以我这里使用的是 14.3.0 版本：

安装完 Umi 之后，我们就可以通过 Umi 提供的指令来创建界面了，我们可以通过 npx umi 指令 来创建一个界面，npx umi 是什么意思呢？npx 是不是在本地的 node_modules 里面找，我后面写的是什么是不是 umi，找到 umi 之后，我要使用 umi 的指令，来创建页面，那么使用什么指令呢？

umi 的什么指令可以创建页面呢？很简单写上一个 g，g 就是创建的单词，然后再后面写上 page 就代表着我需要创建一个界面，在后面再写上你需要创建页面的名称叫什么，最终指令：

npx umi g page index

这样就可以了，在终端中输入这个指令，然后回车，就可以创建一个页面了：

告诉我创建成功了，这个时候回到项目当中，查看一下目录情况，多了一个 pages，自动生成的页面就在这个 pages 里面（通过 Umi 创建界面会自动给我创建一个 pages 目录）：

目录当中分别有两个文件，一个是 index.js，一个是 index.css，这个 index.js 就是我们创建的页面，这个页面是一个 React 组件，index.css 是这个页面的样式文件。

继续回到 index.js 看里面的内容，首先是导入了一个 React，然后导入了一个样式文件，然后就是定义了一个组件，把这个组件暴露出去了，在组件当中有一个 h1，在 h1 里面用模块化的方式，应用了它编写的样式，这个样式就是设置了一下 background 的颜色等于 rgb(242, 233, 121)。

好，这个时候不管三七二十一，先启动项目运行起来看看，怎么运行呢？还是一样的从本地的 node_modules 里面找到 umi，然后使用 umi 的指令，来启动项目，那么启动项目的指令是什么呢？umi 的什么指令可以启动项目呢？很简单，写上一个 dev，dev 就是开发的意思，最终指令：

npx umi dev

运行之前再来看看项目，目前为止，我们项目当中分别有什么文件夹，首先第一个是不是就是 node_modules，第二个是不是就是 pages，第三个是不是就是 package.json，知道这些之后，在终端中输入运行指令，然后回车，项目就会启动起来。

启动过程中我发生了一个异常，异常信息太乱，我大致说明一下原因是因为项目中缺少 webpack 依赖。在使用 UmiJS 时，需要安装 webpack 作为开发依赖。

安装 webpack 依赖：

npm install webpack webpack-cli --save-dev

我这里安装的 webpack 版本是 ^5.97.1，webpack-cli 版本是 ^6.0.1，版本号最好和我这里的一样，这样就可以避免一些不必要的问题。

安装完 webpack 之后，再次运行项目，项目就可以正常启动了：

在回到项目当中查看目录结构，它把项目编译运行起来之后，我发现我项目当中多了一个 .umi 的目录，这个目录是什么呢？

这个文件夹是 Umi 帮我自动生成的可运行的一些相关文件相关配置，在 .umi 文件夹当中有一个比较重要的东西，在 .umi 文件夹当中有一个 core 文件夹，这个 core 文件夹当中有一个 routes.ts 文件，这个东西是什么？

这个东西就是它帮我们配置的一些路由，我们将这个路由文件打开，打开之后，从始至终我们有配置过路由吗？没有，但是它帮我们自动生成了一个路由，这个就可以说明，我们只要创建好一个界面之后它就会自动帮我们把这个界面的路由配置好。

通过观察文件它给我配置了一个 / 的这么一个路由，如果说匹配到了这个路由地址，它就会去渲染 @/pages/index.js 这个页面。

怎么验证呢？验证方式是不是非常的明确与简单呢？直接在浏览器当中打开我们编译好的项目给出的地址：

当我在浏览器中打开这个地址的时候，其实访问的就是 / 这个路由，然后它就会去渲染 @/pages/index.js 这个页面，这个页面就是我们刚刚创建的页面。

这个叫什么？这个就是叫核心路由，这个就是 Umi 自动帮我生成的路由，这个就是约定式的路由！

2.3 约定式路由

什么是约定式路由呢？首先回到项目中，先将项目停掉，我在通过 npx umi g page home 创建一个 home 页面：

home.js 是不是 Umi 帮我们定义的组件，home.css 是不是 Umi 帮我们定义的样式，紧接着我再来创建一个 about 页面：

npx umi g page about

创建完之后，项目的目录又会出现新的两个文件，一个是 about.js，一个是 about.css：

这些内容都有了之后，其实都不重要，我是不是说过 Umi 是以路由为基础的，我是不是说过 Umi 会自动给我们配置一个路由，我是不是说 Umi 自动配置路由，就是约定式路由，又要回到之前的问题，什么是约定式路由呢？

约定式路由又叫做文件路由，就是不用不需要我们手写路由配置，通过目录和文件的名称就能够自动分析和配置路由，这个就是（称之为）约定式路由。

怎么自动分析与配置的呢？

1. 首先呢 Umi 会看 pages 目录，其实 pages 对应的就是 /。

注意点：

• 在约定式路由中，pages 目录就表示路由地址 /
• 在约定式路由中，index.js 文件比较特殊，它对应的就是 / 路由地址渲染的内容

那么也就是说 / 这个路由地址，它将来要渲染的就是 index.js，这个比较特殊。

• 在约定式路由中，其它文件的名称就是路由地址

比如说，我之前创建的 about，它对应的路由地址就是 /about，这个 about 的文件是不是存储在 pages 目录下，所以最终生成的路由地址是什么？

• pages 路由地址是 /
• about 文件存储在 pages 目录下，所以 about 的路由地址是 /about（pages + about）

home 也是同理可证。index.js 文件比较特殊我上面也讲过了，所以该项目中的所有文件我都讲清楚了。

最终生成的路由地址为：

• /：index.js
• /about：about.js
• /home：home.js

怎么进一步的验证我的说法呢？运行 npx umi dev 启动项目，运行之前我先观察 .umi 文件夹下的 core 文件夹下的 routes.ts 文件，看看它帮我配置了什么路由：

这个时候运行项目，Umi 就会根据 pages 下面的文件去给我们生成路由，只要编译好就生成好了，生成好之后回到 .umi 文件夹下的 core 文件夹下的 routes.ts 文件，看看它帮我们配置了什么路由：

通过观察，我们发现它帮我们配置了三个路由，一个是 /，一个是 /about，一个是 /home，分别对应的就是 index.js，about.js，home.js。是不是和我之前说的一样，那怎么再进一步的验证，回到网页当中，打开浏览器，输入 http://localhost:8000/：

是不是访问的就是 index.js，然后再输入 http://localhost:8000/about：

是不是访问的就是 about.js，然后再输入 http://localhost:8000/home：

这个呢就是什么叫约定式路由，约定式路由就是文件路由，约定式路由就是会自动根据文件的名称来生成路由。

三、总结

本文主要介绍了以下内容：

1. Umi 框架概述
   • Umi 是蚂蚁金服的底层前端框架
   • 以路由为基础，支持插件化的企业级 React 框架
   • 核心特性是路由和插件系统
2. 环境搭建
   • NodeJS 环境配置(推荐 14.x 版本)
   • Umi 框架安装(v3.2.24)
   • Webpack 相关依赖配置
3. 约定式路由特点
   • 无需手动配置路由
   • 基于目录结构自动生成路由配置
   • pages 目录对应根路由 /
   • index.js 为默认路由页面
   • 文件名即路由路径
4. 实战经验
   • 项目初始化流程
   • 页面创建与路由生成
   • 路由访问验证方法

通过学习和实践，我们掌握了 Umi 框架的基础使用方法，特别是其约定式路由的核心特性。这为后续开发大型 React 应用打下了良好基础。

🐤如果您觉得本文对您有所帮助，欢迎点赞、收藏或分享，您的支持是我创作的最大动力！

感谢阅读