defineConfig 配置详解

umi 的配置文件是一个正常的 node 模块，它在执行 umi 命令行的时候使用，并且不包含在浏览器端构建中。

特别注意所有的配置文件 config.ts 里面必须写

注意

由于环境不同,但是所有的配置在 config.ts 里面必须有

注意

关于浏览器端构建需要用到的一些配置，还有一些在样式表现上产生作用的一些配置，在 umi 中被统一称为“运行时配置”，你可以在运行时配置看到更多关于它的说明。

这里有一个最简单的 umi 配置文件的范例

import { defineConfig } from "umi";

export default defineConfig({
  outputPath: "dist",
});

alias(重点)

类型: string
默认值: {}

配置别名，用于路径映射。

案例如下:

import { defineConfig } from "umi";

export default defineConfig({
  alias: {
    "@assets": "/src/assets", // 配置别名
  },
});

使用

import yay from "@assets/yay.jpg";

注意

绝对路径

bash

// ⛔
{
  alias: {
    foo: 'foo',
  }
}

// ✅
{
  alias: {
    foo: require.resolve('foo'),
  }
}

如果不希望子路径被映射，可以添加一个$后缀

bash

// import 'foo/bar' 会被映射到 import '/tmp/to/foo/bar'
{
  alias: {
    foo: '/tmp/to/foo',
  }
}

// import 'foo/bar' 还是 import 'foo/bar'，不会被修改
{
  alias: {
    foo$: '/tmp/to/foo',
  }
}

base(重点)

类型 string
Default: /

设置路由前缀,通常用于部署在非根目录

比如你有路由/和/users 然后设置了 base 为/foo/

那你就可以通过/foo/和/foo/users/访问之前的路由

clientLoader(重点)

类型{}
默认值: false

开启后，可以为每个路由声明一个数据加载函数 clientLoader，将页面需要的加载数据程序提取到 clientLoader 可以让 Umi 提前在页面组件尚未加载好的时候提前进行数据的加载，避免瀑布流请求的问题

示例

// .config.development.ts
export default {
  clientLoader: {},
};

配置开启后,在路由组件中使用

// pages/.../some_page.tsx

import { useClientLoaderData } from "umi";

export default function SomePage() {
  const { data } = useClientLoaderData();
  return <div>{data}</div>;
}

export async function clientLoader() {
  const data = await fetch("/api/data");
  return data;
}

crossorigin(重点)

配置 script 标签的 crossorigin。如果有声明，会为本地 script 加上 crossorigin="anonymous" 的属性。

比如:

crossorigin: {
}

举例如下:

html

-
<script src="/umi.js"></script>
+
<script src="/umi.js" crossorigin="anonymous"></script>

cssPublicPath(重点)

类型 string
默认值 ./

为 CSS 中的图片、文件等外部资源指定自定义公共路径。作用类似于 publicPath 默认值是 ./

define(重点)

类型:Object
默认值;{}

用于提供给代码中可用的变量

比如:

  define: {
    "process.env": {
      UMI_ENV: process.env.UMI_ENV,
      domain: "正式环境",
    },
  },

访问

import { useEffect } from "react";

export default function HomePage() {
  useEffect(() => {
    console.log(process.env, process.env.domain);
  }, []);
  return (
    <div>
      <h2>
        Yay! Welcome to umi! - {process.env.domain}-{process.env.UMI_ENV}
      </h2>
    </div>
  );
}

favicons(重点)

类型 string[]
默认值 null

默认情况下，站点将使用约定 favicon 来创建图标的 meta 头标签。

favicons: [
  // 完整地址
  "https://domain.com/favicon.ico",
  // 此时将指向 `/favicon.png` ，确保你的项目含有 `public/favicon.png`
  "/favicon.png",
];

hash(重点)

类型 boolean
默认值 false

配置是否让生成的文件包含 hash 后缀，通常用于增量发布和避免浏览器加载缓存。

headScripts(重点)

类型 string[]
默认值 []

配置在页面中插入的 script 标签。

headScripts: [
  // 完整地址
  "https://domain.com/your-script.js",
  // 此时将指向 `/your-script.js` ，确保你的项目含有 `public/your-script.js`
  "/your-script.js",
];

history(重点)

类型 { type: 'browser' | 'hash' | 'memory' }
默认值 { type: 'browser' }

配置路由类型，可选值为 browser、hash、memory。

historyWithQuery(重点)

类型{}
默认值 false

让 history 带上 query。除了通过 useNavigate 进行的跳转场景，此时还需自行处理 query。

icons(重点)

icon 合集: https://icones.js.org/

具体支持哪个图标库鼠标放到 icon 属性上面即可出现

<Icon icon="ant-design:alipay-circle-filled" width="50" height="50" />

icon 合集使用

在 umi 配置文件设置，开启 icons 功能，并允许自动安装图标库。

 // config.development.js
  icons:{
    autoInstall: {
      "@iconify-json/ant-design": true, //自动安装@iconify-json/ion(换成你自己的)
    },
    include: ["ant-design:alipay-circle-filled"], //要使用的必须把icon类名加到include中，否则无法使用
  },

使用

import { Icon } from "umi";
<Icon icon="ant-design:alipay-circle-filled" width="50" height="50" />;

本地 icon 使用

在 umi 配置文件设置，开启 icons 功能。

本地 svg icon 的使用需要把 svg 保存在 src/icons 目录下，然后通过 local 这个前缀引用

比如在 src/icons 目录下有个 umi.svg，然后可以这样引用。

import { Icon } from "umi";
<Icon icon="local:umi" />;

配置项介绍

autoInstall 表示是否自动安装 icon 集；tnpm/cnpm 客户端暂不支持，但可以通过手动按需安装对应 icon 集合包 @iconify-json/collection-name 。参考：Icon 集合列表, collection-name 为列表中的 Icon set prefix 项。
alias 用于配置 icon 的别名，比如配置了 alias:{home:'fa:home'} 后就可以通过 icon="home" 使用 fa:home 这个 icon 了
include 表示要使用的 icon，比如 include:['fa:home','fa:star'] 就表示只使用 fa:home 和 fa:star 这两个 icon，其他 icon 将不会被打包进最终的产物中。

Icon 组件属性

icon，指定 icon
width，svg 宽度
height，svg 高度
viewBox，svg viewBox
style，外部容器样式
className，外部容器样式名
spin，是否自动旋转
rotate，配置旋转角度，支持多种格式，比如 1，"30deg"、"25%" 都可以
flip，支持 vertical、horizontal，或者他们的组合 vertical,horizontal

inlineLimit(图片重点)

配置图片是否走 base64 编码，默认 10000 字节

类型 number
默认值 10000(10K)

配置图片文件是否走 base64 编译的阈值。默认是 10000 字节，少于他会被编译为 base64 编码，否则会生成单独的文件。

links (重点)

配置额外的 link 标签

links: [{ href: '/foo.css', rel: 'preload' }],

metas(重点)

配置额外的 meta 标签,TDK

metas: [
  { name: 'keywords', content: 'umi, umijs' },
  { name: 'description', content: 'React framework.' },
],

outputPath(重点)

类型 string
默认值 dist

配置输出路径。

注意：不允许设定为 src、public、pages、mock、config、locales、models 等约定式功能相关的目录。

plugins(重点)

类型 string[]
默认值 []

配置需要加载的插件。

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

plugins: [
  // npm 依赖
  'umi-plugin-hello',
  // 相对路径
  './plugin',
  // 绝对路径
  `${__dirname}/plugin.js`,
],

proxy(代理重点)

类型 object
默认值 {}

配置代理。

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

然后访问 /api/users 就能访问到 http://jsonplaceholder.typicode.com/users 的数据。

注意 proxy 配置只会在开发环境生效，生产环境不会生效。

publicPath(重点)

类型 string
默认值 /

配置 webpack 的 publicPath。

routes(重点)

类型 Route[]
默认值 []

配置路由

styles(重点)

类型 string[]
默认值 []

配置额外的样式文件，可以是 css、less、sass 等。

styles: [
  // 完整地址
  "https://domain.com/your-style.css",
  `body { color: red; }`,
];

会生成以下 HTML

html

<style>
  body {
    color: red;
  }
</style>
<link rel="stylesheet" href="https://a.com/b.css" />

vite (重点)

类型 object
默认值 {}

开发者的配置会 merge 到 vite 的默认配置。

示例:

// 更改临时文件路径到 node_modules/.bin/.vite 文件夹
vite: {
  cacheDir: 'node_modules/.bin/.vite',
}

sass-loader

类型 object
默认值 {}

配置 sass-loader

styleLoader

类型 object
默认值 false

启用 style loader 功能，让 CSS 内联在 JS 中，不输出额外的 CSS 文件。

targets

类型 object
默认值 {chrome: 80 }

配置需要兼容的浏览器最低版本。Umi 会根据这个自定引入 polyfill、配置 autoprefixer 和做语法转换等。

示例:

// 兼容 ie11
targets: {
  ie: 11,
}

theme(less 主题)

类型 object
默认值 {}

配置 less 变量主题。


theme: { '@primary-color': '#1DA57A' }

analyze(性能优化)

类型: boolean | object
默认值: {}

包模块结构分析工具，可以看到项目各模块的大小，按需优化。通过 ANALYZE=1 umi build 或 ANALYZE=1 umi dev 开启，默认 server 端口号为 8888，更多配置如下：

package.json

bash

"analyze": "cross-env ANALYZE=1 UMI_ENV=development umi dev" // 开发环境

config.development.ts(不同的环境配置文件)

bash

{
  // 配置具体含义见：https://github.com/umijs/umi-webpack-bundle-analyzer#options-for-plugin
  analyze: {
    analyzerMode: 'server',
    analyzerPort: 8888,
    openAnalyzer: true,
    // generate stats file while ANALYZE_DUMP exist
    generateStatsFile: false,
    statsFilename: 'stats.json',
    logLevel: 'info',
    defaultSizes: 'parsed', // stat  // gzip
  }
}

autoprefixer

类型 object
Default: {flexbox:'no-2009'}

自动添加浏览器前缀解决兼容性问题

注意

不要设置 overrideBrowserslist，此配置被内部接管，通过 targets 配置项选择你要兼容的浏览器

chainWebpack

类型 function
Default: function(chainConfig) { return chainConfig }

通过 webpack-chain 的 API 修改 webpack 配置。

例如:


  chainWebpack(memo, { env, webpack, createCSSRule }) {
    // 设置 alias
    memo.resolve.alias.set("foo", "/tmp/a/b/foo");
    // 删除 umi 内置插件
    memo.plugins.delete("progress");
    memo.plugins.delete("friendly-error");
    memo.plugins.delete("copy");
  },

参数有:

memo:当前 webpack-chain 对象
env:当前环境development,production和test等等
webpack:当前 webpack 实例,用于获取其内部插件
createCSSRule:用于扩展其他 CSS 实现，比如 sass, stylus

cssLoader

类型 object
Default: {}

一般不用动.用来设置引入 css 文件的一些配置

copy

类型 string[]
Default: []

配置要复制到输出目录的文件或文件夹。

当配置字符串时，默认拷贝到产物目录，如：

copy: ["foo.json", "src/bar.json"];

会产生如下产物结构:

bash

+ dist
  - bar.json
  - foo.json
+ src
  - bar.json
- foo.json

你也可以通过对象配置具体的拷贝位置，其中相对路径的起点为项目根目录：

copy: [
  { from: "from", to: "dist/output" },
  { from: "file.json", to: "dist" },
];

会产生如下结构

bash

+ dist
  + output
    - foo.json
  - file.json
+ from
  - foo.json
- file.json

lessLoader

设置 less-loader 的 Options。

注意

默认是用 less@4 版本

legacy(兼容低版本浏览器)

当你需要兼容低版本浏览器时，可能需要该选项，开启后将默认使用非现代的打包工具做构建，这会显著增加你的构建时间。

postcssLoader

类型object
默认值 {}

defineConfig 配置详解 ​

alias(重点) ​

注意 ​

base(重点) ​

clientLoader(重点) ​

示例 ​

crossorigin(重点) ​

cssPublicPath(重点) ​

define(重点) ​

favicons(重点) ​

hash(重点) ​

headScripts(重点) ​

history(重点) ​

historyWithQuery(重点) ​

icons(重点) ​

icon 合集使用 ​

本地 icon 使用 ​

配置项介绍 ​

Icon 组件属性 ​

inlineLimit(图片重点) ​

links (重点) ​

metas(重点) ​

outputPath(重点) ​

plugins(重点) ​

proxy(代理重点) ​

publicPath(重点) ​

routes(重点) ​

styles(重点) ​

vite (重点) ​

sass-loader ​

styleLoader ​

targets ​

theme(less 主题) ​

analyze(性能优化) ​

autoprefixer ​

chainWebpack ​

参数有: ​

cssLoader ​

copy ​

lessLoader ​

legacy(兼容低版本浏览器) ​

postcssLoader ​

defineConfig 配置详解

alias(重点)

注意

base(重点)

clientLoader(重点)

示例

crossorigin(重点)

cssPublicPath(重点)

define(重点)

favicons(重点)

hash(重点)

headScripts(重点)

history(重点)

historyWithQuery(重点)

icons(重点)

icon 合集使用

本地 icon 使用

配置项介绍

Icon 组件属性

inlineLimit(图片重点)

links (重点)

metas(重点)

outputPath(重点)

plugins(重点)

proxy(代理重点)

publicPath(重点)

routes(重点)

styles(重点)

vite (重点)

sass-loader

styleLoader

targets

theme(less 主题)

analyze(性能优化)

autoprefixer

chainWebpack

参数有:

cssLoader

copy

lessLoader

legacy(兼容低版本浏览器)

postcssLoader