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，默认browser
	history: { 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