react+umi+antd项目搭建配置

官方文档链接：
UmiJS官方文档
React官方文档
Ant Design官方文档

一、项目搭建

对于react umi项目搭建，umi官方文档已经写的很清晰了，具体请查看上面的umi官方文档链接。这里我不再详细说明，着重说明一些需要注意的地方。

1. 首先，确认是否已安装node和umi，本文umi版本使用3.0版本。

$ node -v
$ umi -v

2. 可通过以下两种命令创建项目，但创建出来的项目umi版本不同

$ yarn create umi
说明：
使用此命令创建的项目，umi版本为2.x版本，如需使用3.x版本还需要手动升级，关于手动升级的操作umi官网也有详细步骤
除此之外，此命令可选择创建哪种项目，如需使用ant-design-pro框架可使用此法创建（如下图）$ yarn create @umijs/umi-app
说明：
此命令为umi官网提供的项目创建工具，创建完成umi项目即为3.x版本推荐使用

注意：以上两种创建方式都需要手动安装 antd 依赖，项目工程默认自带的是 @ant-design/pro-layout ，但pro-layout相关文档阅读体验不够好，个人比较推荐直接使用 antd （使用ant-design-pro框架除外）

二、ESLint相关配置

umi项目的lint相关配置使用 @umijs/fabric 就已经足够了，运行过程中如果有什么依赖找不到直接yarn安装就行。

1. 新增 .eslintrc.js、.eslintignore、.stylelintrc.js、.stylelintignore 配置文件

eslintrc.js

module.exports = {extends: [require.resolve('@umijs/fabric/dist/eslint')],rules: {'no-unused-vars': 'warn','@typescript-eslint/no-unused-vars': 'warn'},
}

.stylelintrc.js

module.exports = {extends: [require.resolve('@umijs/fabric/dist/stylint')]
};

prettierrc相关配置使用项目创建时默认的就行，不用修改。

2. 配置lint相关命令（仅供参考，可根据需求灵活配置）

"lint": "umi g tmp && yarn lint:js && yarn lint:style && yarn lint:prettier",
"lint:prettier": "prettier --check \"**/*\" --end-of-line auto",
"lint:fix": "eslint --fix --cache --ext .js,.jsx,.ts,.tsx --format=pretty ./src && npm run lint:style",
"lint:js": "eslint --cache --ext .js,.jsx,.ts,.tsx --format=pretty ./src",
"lint:style": "stylelint --fix \"src/**/*.less\""

三、Umi项目配置

1. 两种配置方式（推荐config方式）

详见：https://umijs.org/zh-CN/docs/config

注意，使用config配置方式需注意config文件夹所在目录为根目录，不要配错到src目录之下了！

2. 两种路由配置方式（约定式路由与配置式路由）

详见：https://umijs.org/zh-CN/docs/convention-routing

注意：如需配置不在 / 根路由下的独立路由页面（如登录页），避免访问此独立页面时，此页面嵌入到了 layout 中，可通过配置式路由将独立页面放到根路由配置到上方，路由时首先匹配到了独立页面就不会继续匹配根路由下的子页面，从而避免出现独立页面嵌套 layout 的情况。

3. 两种 `layout` 布局方式

1）config配置layout（不推荐）

config/config.ts

import { defineConfig } from 'umi';export default defineConfig({ title: '管理系统', layout: { name: '这是菜单', locale: false }routes: [{path: '/dashboard',name: 'dashboard',icon: 'dashboard',}，...]
})

配置好 layout 和路由后，按照路由创建对应页面组件即可

2）在src目录下新增 layouts 布局文件夹配置（推荐）
在项目src目录创建 layouts 文件夹，项目运行时会自动读取此文件路径下的布局组件。

布局时，使用 @ant-design/pro-layout 或 antd 两种UI组件其中某一种皆可，我使用的是antd组件库的布局组件。

详见：布局 Layout - Ant Design

4. 全局配置

1）全局样式
在src文件夹下创建global.less样式文件，此样式文件中设置的样式会全局生效，可将公共样式放到此文件中

2）入口html文件
在 src/pages目录下创建document.ejs文件，文件内容为html，此文件默认是umi的入口html文件，类似于Vue项目中public/index.html文件

5. Umi的其他常用配置说明

1）devServer
如果你想像Vue中，在vue.config.js配置服务器端口号之类的信息可以使用devServer配置。

import { defineConfig } from 'umi';export default defineConfig({devServer: {port: 3000,}
})

2）chainWebpack

如果你想要修改webpack配置，或使用各种webpack插件，可通过此配置来实现

import { defineConfig } from 'umi';
import XXPlugin from 'xx-plugin'export default defineConfig({chainWebpack(config, { webpack }) {config.plugin('XXPlugin').use(XXPlugin);}
})

3） dynamicImport
启用按需加载

4）hash

如果配置了hash: true ，会让dist目录下生成的文件包含 hash 后缀，如下logo.[hash字符].png

+ dist- logo.sw892d.png- umi.df723s.js- umi.8sd8fw.css- index.html

5）alias

Vue:

chainWebpack: (config) => {config.entry('app').clear()config.entry('app').add('./src/main.js')config.resolve.alias.set('@', resolve('src')).set('@utils', resolve('src/utils')).set('@assets', resolve('src/assets'))}

Umi:

import { defineConfig } from 'umi';export default defineConfig({// 配置别名，对引用路径进行映射。alias: {'@utils': '/src/utils','@assets': '/src/assets'}
})

6）history
可通过history配置哈希路由，注意不要和hash配置混淆。

import { defineConfig } from 'umi';export default defineConfig({// 配置路由模式为hash模式，type可选 browser、hash 和 memory，默认browserhistory: { type: 'hash' }
})

7） theme
如果想要定制不同主题，可通过theme配置主题样式变量，变量为less变量

// config.ts
import { defineConfig } from 'umi';
import theme from './theme';export default defineConfig({theme: theme
})

// theme.ts
export default {'@headerColor': '#0099FF','@menuFontColor': '#001949',
};

8）cssLoader
若希望将 ClassName 类名变成驼峰命名形式，可设置

import { defineConfig } from 'umi';export default defineConfig({cssLoader: {localsConvention: 'camelCase',}
})

设置之后，在具体页面中，className会被解析成驼峰形式

import React from 'react';import styles from './index.less'; // .bar-foo { font-size: 16px; }export default () => <div className={styles.barFoo}>Hello</div>;
// => <div class="bar-foo___{hash}">Hello</div>

9）外部js和css文件引入
如果想要引入其他的外部css文件或js文件，如iconfont字体文件等，可通过scripts和styles配置进行设置

import { defineConfig } from 'umi';export default defineConfig({scripts: ['//at.alicdn.com/t/font_XXXX.js'， 'XXX.js'],styles: ['//at.alicdn.com/t/font_XXXX.css', 'XXX.css'],
})

更多配置请参考官方文档配置说明：https://umijs.org/zh-CN/config

注意：若你在项目中进行了静态化配置，你会发现你在通过路由访问页面的时候无法访问到对应的页面，需要加一个.html后缀才能正常访问。如http://127.0.0.1/login路由页面需要访问http://127.0.0.1/login.html才能正常访问页面(坑～，初次配置的时候不小心加了这个配置，结果找了好久路由无法访问页面的问题！)

// 如果htmlSuffix为true，umi生成的路由文件会自动加上.html后缀
exportStatic: {htmlSuffix: true
},

还有一点需要注意，如果你发现你的项目采用的是 history 模式，且部署到服务器上之后，刷新页面时路由地址会自动追加一个一个 / ，导致页面访问空白或重定向，但本地调试不会有问题，这也有可能是配置里配置了 exportStatic 的问题，需要注意的是，即使没有配置htmlSuffix 仅仅是空的 exportStatic: {} 配置也不行！

具体问题参考umi的github issues：项目部署后，浏览器刷新后，url pathname尾部会多出一个 / #9140

四、项目目录结构（参考）


├── config├── config.ts
├── dist
├── mock
├── public
└── src├── .umi├── api├── assets├── components├── utils├── layouts├── index.less└── index.tsx├── pages└── login├── index.less└── index.tsx├── app.ts└── global.less 
├── .env
├── .editorconfig
├── .eslintrc.js
├── .eslintignore
├── .stylelintrc.js
├── .stylelintignore
├── tsconfig.json
├── package.json
├── README.md