umi 是一个企业级 react 应用框架，也是蚂蚁金服的底层前端框架
一、安装脚手架
在创建项目之前，需要保证有 node 8.10 以上的环境
可以使用官方脚手架 create-umi 快速创建项目
首先创建一个新目录
mkdir myapp && cd myapp
然后直接创建项目
yarn create umi
// 或
npm create umi
如果提示 create-umi 命令不存在，可以先执行 yarn global bin ，然后把 global bin 的路径添加到 PATH 环境变量里
另外也可以选择手动安装 create-umi 并执行
$ npm install create-umi -g
$ create-umi
二、按需创建项目
选择 app 创建一个 umi 应用
选择是否使用 typeScript，默认不使用
然后使用空格键选择需要的功能，功能介绍详见 plugin/umi-plugin-react
这里的 antd 和 dva 可以不用选，只要创建项目后配置相应的插件，就能在项目中内置 antd、antd-mobile 和 dva
然后就会生成如下的项目
现在可以使用 yarn start 命令启动项目了，在浏览器中访问 http://localhost:8000 可以查看预置页面
三、配置插件
根目录下的 .umirc.js 是整个应用的配置文件，上面提到的插件也可以在这里配置
配置项可以写在 .umirc.js 文件中，也可以写在 config/config.js 文件中，二者只有一个生效
完整的配置项可以参考文档，这里介绍几个比较实用的配置项：
1. proxy
const HOST_URL = '';
export default { proxy: { '/api': { target: HOST_URL, changeOrigin: true, pathRewrite: { '/api': '' }, }, }, }
2. theme
全局配置 less 变量（umi 项目默认使用 less）
export default {
theme: {
'primary-color': '#3385ff',
'font-size-base': '14px',
},
}
然后在 less 文件顶部引入
@import '~antd/lib/style/themes/default.less';
就能直接使用配置的 theme 变量了
3. routes
umi 会基于约定的 pages 目录自动生成路由
如果更倾向于使用配置路由，可以在配置文件中单独配置 routes
export default {
routes: [
{ path: '/', component: './a' },
{ path: '/list', component: './b', Routes: ['./routes/PrivateRoute.js'] },
{ path: '/users', component: './users/_layout',
routes: [
{ path: '/users/detail', component: './users/detail' },
{ path: '/users/:id', component: './users/id' }
]
},
],
};
配置项中的 component 路径是从 src/pages 目录开始解析的
⚠️注意：routes 配置项存在时则不会对 src/pages 目录做约定式的解析，即约定式路由无法生效
4.alias
可以配置 webpack 的 resolve.alias 属性
alias: {
'@': require('path').resolve(__dirname, './src'),
'@components': require('path').resolve(__dirname, './src/components'),
},
配置之后在 import 的时候可以使用快捷路径
另外根目录下有一个 webpack.config.js，这里也有配置 alias，但这里的 alias 不会在项目中生效
5.devServer
官方文档上说可以配置 devServer
但实际上直接配置 devServer 是无效的
而图上提到的 https、port 等需要使用 .env 文件来配置环境变量
BROWSER=none
ESLINT=1
PORT=9000 // 自定义本地服务端口
这里定义的系统环境变量在整个 umi-build-dev 的生命周期里都可以被使用
四、约定目录
umi 对于项目中的目录有严格的约定，路由、model 都是基于目录结构实现
.
├── dist/ // 默认的 build 输出目录
├── mock/ // mock 文件所在目录，基于 express
├── config/
├── config.js // umi 配置，同 .umirc.js，二选一
└── src/ // 源码目录，可选
├── layouts/index.js // 全局布局
├── pages/ // 页面目录，里面的文件即路由
├── .umi/ // dev 临时目录，需添加到 .gitignore
├── .umi-production/ // build 临时目录，会自动删除
├── document.ejs // HTML 模板
├── 404.js // 404 页面
├── page1.js // 页面 1，任意命名，导出 react 组件
├── page1.test.js // 用例文件，umi test 会匹配所有 .test.js 和 .e2e.js 结尾的文件
└── page2.js // 页面 2，任意命名
├── global.css // 约定的全局样式文件，自动引入，也可以用 global.less
├── global.js // 可以在这里加入 polyfill
├── app.js // 运行时配置文件
├── .umirc.js // umi 配置，同 config/config.js，二选一
├── .env // 环境变量
└── package.json
以上的目录除了 pages 下面的自定义页面文件以外，都不可以重命名
如果需要给整个项目添加一个静态 HTML 模版，可以新建一个 src/pages/document.ejs 文件
但这个 document.ejs 文件必须包含 <div id="root"></div>
五、路由与页面跳转
如果采用约定式路由，pages 目录下的页面需要严格遵守相关规范
具有 $ 前缀的页面会被识别为动态路由
pages/users/$id.js
-> path: '/users/:id'
同时具备 $ 前缀和后缀的页面会被识别为可选的动态路由
pages/users/$id$.js
-> path: '/users/:id?'
当目录下存在 _layout.js 文件时，会以 _layout.js 作为基础页面生成嵌套路由
+ pages/
+ users/
- _layout.js
- $id.js
- index.js
以上的目录结构会生成：
[
{ path: '/users', component: './pages/users/_layout.js',
routes: [
{ path: '/users/', component: './pages/users/index.js' },
{ path: '/users/:id', component: './pages/users/$id.js' },
],
},
]
在页面中可以通过 umi/router 提供的 API 跳转页面
import router from 'umi/router';
function goToList() {
router.push('/list');
}
或者使用 umi/link 作为组件跳转
import Link from 'umi/link';
export default () => (
<Link to="/list">Go to list page</Link>
);