配置项

在项目根目录创建 .umirc.tsconfig/config.ts 文件,都可对 dumi 进行配置:

// 配置文件
export default {
// 具体配置项
};

目前 dumi 支持以下配置项。

基础配置

algolia

  • 类型: Object
  • 默认值:null
  • 详细:

配置 Algolia 的 DocSearch 服务,通常你会需要启用 sitemap.xml 的自动生成,以便顺利接入 Algolia,参考 配置项 - sitemap

示例:

{
algolia: {
apiKey: 'yourapikey',
indexName: 'dumi',
}
}

如果你的网站不符合 DocSearch 免费标准,可以自行注册 Algolia 账号并部署爬虫。这种情况下需要提供 appId

{
algolia: {
appId: 'yourappid',
apiKey: 'yourapikey',
indexName: 'dumi',
}
}

apiParser

  • 类型:Object
  • 默认值:{}
  • 详细:

配置 API 解析的行为,支持以下配置项:

{
apiParser: {
// 自定义属性过滤配置,也可以是一个函数,用法参考:https://github.com/styleguidist/react-docgen-typescript/#propfilter
propFilter: {
// 是否忽略从 node_modules 继承的属性,默认值为 false
skipNodeModules: false,
// 需要忽略的属性名列表,默认为空数组
skipPropsWithName: ['title'],
// 是否忽略没有文档说明的属性,默认值为 false
skipPropsWithoutDoc: false,
},
}
}

description

  • 类型:String
  • 默认值:null
  • 详细:

配置文档的介绍,会显示在侧边栏菜单标题的下方,仅 doc 模式下可用。

  • 类型:String
  • 默认值:Umi 的 LOGO
  • 详细:

配置文档的 LOGO。

如果是使用本地图片,比如:/public/images/xxx.png,那么配置 /images/xx.png 引入即可。

locales

  • 类型:Array<[String, String]>
  • 默认值:[['en-US', 'English'], ['zh-CN', '中文']]
  • 详细:

该配置为二维数组,第一项配置会作为站点默认的 locale。

每一项配置是一个长度为 2 的数组,数组的第一个值代表该 locale 的 name,会用于拼接路由前缀和检测文件名属于什么 locale,第二个值代表该 locale 的 label,会用作语言切换时的选项显示。

默认 locale 的文件名后缀是可选的,比如,在默认配置下,index.mdindex.en-US.md 等价。

mode

  • 类型:doc | site
  • 默认值:doc
  • 详细:

用于设定文档的展现模式,默认为文档模式,配置为 site 时可无缝切换为站点模式。如果希望对导航菜单项展示的文本和顺序,可参考 frontmatter 配置中的 nav 配置项。

两种模式的效果如下,文档模式:

站点模式:

  • 类型:Object
  • 默认值:自动生成的菜单
  • 详细:

该配置项用于自定义侧边菜单的展示,目前仅 site 模式下可用,分多语言模式和单语言模式,使用方式:

// config/config.ts 或 .umirc.ts
export default {
menus: {
// 需要自定义侧边菜单的路径,没有配置的路径还是会使用自动生成的配置
'/guide': [
{
title: '菜单项',
path: '菜单路由(可选)',
children: [
// 菜单子项(可选)
'guide/index.md', // 对应的 Markdown 文件,路径是相对于 resolve.includes 目录识别的
],
},
],
// 如果该路径有其他语言,需在前面加上语言前缀,需与 locales 配置中的路径一致
'/zh-CN/guide': [
// 省略,配置同上
],
},
};
  • 类型:Object | Array
  • 默认值:自动生成的导航
  • 详细:

该配置项用于自定义导航栏的展示,仅 site 模式下可用,分多语言模式和单语言模式,使用方式:

// config/config.ts 或 .umirc.ts
export default {
// 单语言配置方式如下
navs: [
null, // null 值代表保留约定式生成的导航,只做增量配置
{
title: 'GitHub',
path: 'https://github.com/umijs/dumi',
},
{
title: '我有二级导航',
path: '链接是可选的',
// 可通过如下形式嵌套二级导航菜单,目前暂不支持更多层级嵌套:
children: [
{ title: '第一项', path: 'https://d.umijs.org' },
{ title: '第二项', path: '/guide' },
],
},
],
// 多语言配置方式如下
navs: {
// 多语言 key 值需与 locales 配置中的 key 一致
'en-US': [
null, // null 值代表保留约定式生成的导航,只做增量配置
{
title: 'GitHub',
path: 'https://github.com/umijs/dumi',
},
],
'zh-CN': [
null, // null 值代表保留约定式生成的导航,只做增量配置
{
title: 'GitHub',
path: 'https://github.com/umijs/dumi',
},
],
},
};

resolve

resolve 是一个 Object 类型,用于配置 dumi 的解析行为,包含如下配置:

resolve.includes

  • 类型:Array<String>
  • 默认值:['docs', 'src'] or ['docs', 'packages/pkg/src']
  • 详细:

配置 dumi 嗅探的文档目录,dumi 会尝试在配置的目录中递归寻找 markdown 文件,默认值为 docs 目录、src 目录(普通项目),如果环境为 lerna 项目,则 src 目录变为 packages/pkg/src 目录,通常不需要配置,除非自动嗅探出现了『误伤』。

注意:

  • 默认的 srcdocs 目录会自动排除 node_modulesfixtures 目录。

resolve.excludes

  • 类型:Array<String>
  • 默认值:[]
  • 详细:

需要排除的目录,会对 dumi 嗅探到的目录或文件进行过滤,规则同 gitignore 配置。

resolve.previewLangs

  • 类型:Array<String>
  • 默认值:['jsx', 'tsx']
  • 详细:

配置 dumi 默认会转换为 ReactComponent 组件渲染的代码块,如果不希望做任何转换,例如类似 Umi 官网的纯站点,那么将该项设置为空数组即可。

resolve.passivePreview

  • 类型:Boolean
  • 默认值:false
  • 详细:

代码块被动渲染模式,当为 true 时,仅将属于 resolve.previewLangs 且具有 preview 修饰符的代码块渲染为 ReactComponent 代码块。一般用于仅希望渲染 resolve.previewLangs 中的少部分代码块,而不是全部。

sitemap

  • Type: { hostname: string, excludes?: string[] }
  • Default: null

启用 sitemap.xml 自动生成特性。hostname 配置项用来指定 URL 的域名前缀,excludes 配置项用来忽略某些不需要包含在 sitemap 中的路由。

title

  • 类型:String
  • 默认值:{package.name}
  • 详细:

配置文档的名称,导航栏或侧边栏上。

themeConfig

  • 类型:Object
  • 默认值:{}
  • 详细:

用于配置当前使用的主题包,具体配置项取决于主题包提供哪些配置,可访问 主题列表 查看目前可用的主题。

更多配置

404

  • Type: boolean
  • Default: true

约定式路由中 404 页面的生效规则,可通过设置为 false 关闭。

alias

  • Type: object
  • Default: {}

配置别名,对引用路径进行映射。

比如:

export default {
alias: {
foo: '/tmp/a/b/foo',
},
};

然后 import('foo'),实际上是 import('/tmp/a/b/foo')

analyze

  • Type: object
  • Default: {}

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

{
// 配置具体含义见: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

  • Type: object
  • Default: { flexbox: 'no-2009' }

设置 autoprefixer 的配置项

注意:

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

base

  • Type: string
  • Default: /

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

比如,你有路由 //users,然后设置了 base 为 /foo/,那么就可以通过 /foo//foo/users 访问到之前的路由。

chainWebpack

  • Type: Function

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

比如:

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

支持异步,

export default {
async chainWebpack(memo) {
await delay(100);
memo.resolve.alias.set('foo', '/tmp/a/b/foo');
},
};

SSR 时,修改服务端构建配置

import { BundlerConfigType } from 'dumi';
export default {
chainWebpack(memo, { type }) {
// 对 ssr bundler config 的修改
if (type === BundlerConfigType.ssr) {
// 服务端渲染构建扩展
}
// 对 csr bundler config 的修改
if (type === BundlerConfigType.csr) {
// 客户端渲染构建扩展
}
// ssr 和 csr 都扩展
},
};

参数有:

  • memo,当前 webpack-chain 对象
  • env,当前环境,developmentproductiontest
  • webpack,webpack 实例,用于获取其内部插件
  • createCSSRule,用于扩展其他 CSS 实现,比如 sass, stylus
  • type,当前 webpack 实例类型,默认走 csr,如果开启 ssr,会有 ssr 的 webpack 实例

chunks

默认是 ['umi'],可修改,比如做了 vendors 依赖提取之后,会需要在 umi.js 之前加载 vendors.js

比如:

export default {
chunks: ['vendors', 'umi'],
chainWebpack: function (config, { webpack }) {
config.merge({
optimization: {
splitChunks: {
chunks: 'all',
minSize: 30000,
minChunks: 3,
automaticNameDelimiter: '.',
cacheGroups: {
vendor: {
name: 'vendors',
test({ resource }) {
return /[\\/]node_modules[\\/]/.test(resource);
},
priority: 10,
},
},
},
},
});
},
};

cssLoader

  • Type: object
  • Default: {}

设置 css-loader 配置项

若希望将 ClassName 类名变成驼峰命名形式,可配置:

{
cssLoader: {
localsConvention: 'camelCase',
}
}

则以下写法将自动转成驼峰命名:

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>

cssModulesTypescriptLoader

  • type: { mode: 'verify' | 'emit' }
  • Default: undefined

对按照 css modules 方式引入的 css 或 less 等样式文件,自动生成 ts 类型定义文件。

比如:

export default {
cssModulesTypescriptLoader: {},
};

等同于以下配置,mode 默认为 emit

export default {
cssModulesTypescriptLoader: {
mode: 'emit',
},
};

cssnano

  • Type: object
  • Default: { mergeRules: false, minifyFontValues: { removeQuotes: false } }

设置 cssnano 配置项,基于 default 的配置集合。

比如:.box { background: url("./css/../img/cat.jpg"); } 默认会被压缩成 .box { background: url(img/cat.jpg); } ,如果不想要这个特性,可以设置,

export default {
cssnano: {
normalizeUrl: false,
},
};

copy

  • Type: Array(string|{from:string,to:string})
  • Default: []

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

比如你的目录结构如下,

+src - index.ts + bar - bar.js - foo.js;

然后设置,

export default {
copy: ['foo.js', 'bar'],
};

编译完成后,会额外输出以下文件,

+dist + bar - bar.js - foo.js;

支持配置 from-to, 需要注意的是 from 是相对于 cwd 的路径,to 是相对于输出路径的路径。

比如你的目录结构如下,

+src - index.ts + bar - bar.js;

然后设置,

export default {
copy: [
{
from: 'bar/bar.js',
to: 'some/bar.js',
},
],
};

编译完成后,会额外输出以下文件,

+dist + some - bar.js;

define

  • Type: object
  • Default: {}

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

比如:

export default {
define: {
FOO: 'bar',
},
};

然后你写 console.log(hello, FOO); 会被编译成 console.log(hello, 'bar')

注意:

  • define 对象的属性值会经过一次 JSON.stringify 转换

内置的 define 属性,

  • process.env.NODE_ENV,值为 developmentproduction

如果你有一些不想在生成环境运行的代码,比如断言判断,可以这样,

if (process.env.NODE_ENV === 'development') {
assert(foo === bar, 'foo is not equal to bar');
}

dev 时正常运行,build 后会变成为,

if (false) {
assert(foo === bar, 'foo is not equal to bar');
}

进而被压缩掉,不输出在生成环境的代码中。

devServer

  • Type: object
  • Default: {}

配置开发服务器。

包含以下子配置项:

  • port,端口号,默认 8000
  • host,默认 0.0.0.0
  • https,是否启用 https server
  • writeToDisk,生成 assets 到文件系统

启用 port 和 host 也可以通过环境变量 PORT 和 HOST 临时指定。

关于 https 配置项。

  • 可以通过 https: truehttps: {} 开启,使用 umi 内置的证书,http/2 也会开启。
  • 如果不希望使用 http/2,可以通过 https: { http2: false } 关闭。(使用 HTTP 2.0 在 Chrome 或 Edge 浏览器中中有偶然出现 ERR_HTTP2_PROTOCOL_ERROR报错,如有遇到,建议使用此配置)
  • 如果希望使用自定义证书,可以通过 https: { cert: '...', key: '...' } 配置, key 和 cert 指定文件路径。

devtool

  • Type: string
  • Default: cheap-module-source-map in dev, false in build

用户配置 sourcemap 类型。

常见的可选类型有:

  • eval,最快的类型,但不支持低版本浏览器,如果编译慢,可以试试
  • source-map,最慢最全的类型

更多类型详见 webpack#devtool 配置

dynamicImport

  • Type: object
  • Default: false

是否启用按需加载,即是否把构建产物进行拆分,在需要的时候下载额外的 JS 再执行。

默认关闭时,只生成一个 js 和一个 css,即 umi.jsumi.css。优点是省心,部署方便;缺点是对用户来说初次打开网站会比较慢。

打包后通常是这样的,

+ dist
- umi.js
- umi.css
- index.html

启用之后,需要考虑 publicPath 的配置,可能还需要考虑 runtimePublicPath,因为需要知道从哪里异步加载 JS、CSS 和图片等资源。

打包后通常是这样,

+ dist
- umi.js
- umi.css
- index.html
- p__index.js
- p__users__index.js

这里的 p__users_index.js 是路由组件所在路径 src/pages/users/index,其中 src 会被忽略,pages 被替换为 p

包含以下子配置项,

  • loading, 类型为字符串,指向 loading 组件文件

比如:

export default {
dynamicImport: {
loading: '@/Loading',
},
};

然后在 src 目录下新建 Loading.tsx

import React from 'react';
export default () => {
return <div>加载中...</div>;
};

构建之后使用低网络模拟就能看到效果。

dynamicImportSyntax

  • Type: object
  • Default: false

如果你不需要路由按需加载,只需要支持 import() 语法的 code splitting,可使用此配置。

比如:

export default {
dynamicImportSyntax: {},
};

exportStatic

  • Type: object

配置 html 的输出形式,默认只输出 index.html

如果需要预渲染,请开启 ssr 配置,常用来解决没有服务端情况下,页面的 SEO 和首屏渲染提速。

如果开启 exportStatic,则会针对每个路由输出 html 文件。

包含以下几个属性:

  • htmlSuffix,启用 .html 后缀。
  • dynamicRoot,部署到任意路径。
  • extraRoutePaths,生成额外的路径页面,用法和场景见 预渲染动态路由

比如以下路由,

/
/users
/list

不开启 exportStatic 时,输出,

- index.html

设置 exportStatic: {} 后,输出,

- index.html
- users/index.html
- list/index.html

设置 exportStatic: { htmlSuffix: true } 后,输出,

- index.html
- users.html
- list.html

若有 SEO 需求,可开启 ssr 配置,在 dumi build 后,会路由(除静态路由外)渲染成有具体内容的静态 html 页面,例如如下路由配置:

// .umirc.ts | config/config.ts
{
routes: [
{
path: '/',
component: '@/layouts/Layout',
routes: [
{ path: '/', component: '@/pages/Index' },
{ path: '/bar', component: '@/pages/Bar' },
{ path: '/news', component: '@/pages/News' },
{ path: '/news/:id', component: '@/pages/NewsDetail' },
],
},
];
}

设置 { ssr: {}, exportStatic: { } 后,输出,

会在编译后,生成如下产物:

- dist
- umi.js
- umi.css
- index.html
- bar
- index.html
- news
- index.html
- [id].html

考虑到预渲染后,大部分不会再用到 umi.server.js 服务端文件,构建完成后会删掉 umi.server.js  文件如果有调试、不删除 server 文件需求,可通过环境变量 RM_SERVER_FILE=none 来保留。

externals

  • Type: object
  • Default: {}

设置哪些模块可以不被打包,通过 <script> 或其他方式引入,通常需要和 scripts 或 headScripts 配置同时使用。

比如,

export default {
externals: {
react: 'window.React',
},
scripts: ['https://unpkg.com/react@17.0.1/umd/react.production.min.js'],
};

简单理解的话,可以理解为 import react from 'react' 会被替换为 const react = window.React

extraBabelIncludes

  • Type: Array
  • Default: []

配置额外需要做 babel 编译的 npm 包或目录。

比如:

export default {
extraBabelIncludes: [
// 支持绝对路径
join(__dirname, '../../common'),
// 支持 npm 包
'react-monaco-editor',
],
};

extraBabelPlugins

  • Type: Array
  • Default: []

配置额外的 babel 插件。

比如:

export default {
extraBabelPlugins: ['babel-plugin-react-require'],
};

extraBabelPresets

  • Type: Array
  • Default: []

配置额外的 babel 插件集。

extraPostCSSPlugins

  • Type: Array
  • Default: []

配置额外的 postcss 插件

favicon

  • Type: string

配置 favicon 地址(href 属性)。

比如,

export default {
favicon: '/assets/favicon.ico',
};

如果要使用本地的图片,图片请放到 public 目录

HTML 中会生成,

<link rel="shortcut icon" type="image/x-icon" href="/assets/favicon.ico" />

forkTSChecker

  • Type: object

开启 TypeScript 编译时类型检查,默认关闭。

fastRefresh

  • Type: object

快速刷新(Fast Refresh),开发时可以保持组件状态,同时编辑提供即时反馈

文档

hash

  • Type: boolean
  • Default: false

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

启用 hash 后,产物通常是这样,

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

注:

  • html 文件始终没有 hash

headScripts

  • Type: Array
  • Default: []

配置 <head> 里的额外脚本,数组项为字符串或对象。

大部分场景下用字符串格式就够了,比如:

export default {
headScripts: [`alert(1);`, `https://a.com/b.js`],
};

会生成 HTML,

<head>
<script>
alert(1);
</script>
<script src="https://a.com/b.js"></script>
</head>

如果要使用额外属性,可以用对象的格式,

export default {
headScripts: [
{ src: '/foo.js', defer: true },
{ content: `alert('你好');`, charset: 'utf-8' },
],
};

会生成 HTML,

<head>
<script src="/foo.js" defer></script>
<script charset="utf-8">
alert('你好');
</script>
</head>

history

  • Type: object
  • Default: { type: 'browser' }

配置 history 类型和配置项

包含以下子配置项:

  • type,可选 browserhashmemory
  • options,传给 create{{{ type }}}History 的配置项,每个类型器的配置项不同

注意,

  • options 中,getUserConfirmation 由于是函数的格式,暂不支持配置
  • options 中,basename 无需配置,通过 dumi 的 base 配置指定

ignoreMomentLocale

  • Type: boolean
  • Default: false

忽略 moment 的 locale 文件,用于减少尺寸。

inlineLimit

  • Type: number
  • Default: 10000 (10k)

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

lessLoader

  • Type: object
  • Default: {}

设置 less-loader 配置项

  • Type: Array
  • Default: []

配置额外的 link 标签。

manifest

  • Type: object

配置是否需要生成额外用于描述产物的 manifest 文件,默认会生成 asset-manifest.json

包含以下子配置项:

  • fileName,文件名,默认是 asset-manifest.json
  • publicPath,默认会使用 webpack 的 output.publicPath 配置
  • basePath,给所有文件路径加前缀
  • writeToFileEmit,开发模式下,写 manifest 到文件系统中

注意:

  • 只在 dumi build 时会生成

metas

  • Type: Array
  • Default: []

配置额外的 meta 标签。数组中可以配置key:value形式的对象。

最终生成的 meta 标签格式为: <meta key1="value1" key2="value2"/>

如以下配置:

export default {
metas: [
{
name: 'keywords',
content: 'dumi, base on umi',
},
{
name: 'description',
content: '📖 为组件开发场景而生的文档工具',
},
{
bar: 'foo',
},
],
};

最终生成的 html 标签是:

<meta name="keywords" content="dumi, base on umi" />
<meta name="description" content="📖 为组件开发场景而生的文档工具" />
<meta bar="foo" />

mfsu

  • Type: Object
  • Default : {}

Turn on the MFSU functionality and add the associated configuration.

Enabling this feature will automatically enable webpack5 and dynamicImport.

Contains sub-attributes

  • development: { output: String }。可以通过 output 自定义 dev 模式下的输出路径。用于将预编译文件同步到 git。
  • production: { output: String }。在生产模式中使用 mfsu。如果额外设置了 output,将会将生产模式预编译依赖编译到 output 下。
  • mfName: string。指定预编译依赖的变量名,默认为 mf,比如可在 qiankun 主应用里配置
  • exportAllMembers
  • chunks: string[]。mfsu 阶段的 chunks 写死了 ['umi'],可通过此配置项强行修改
  • ignoreNodeBuiltInModules: boolean。配为 true 时不预编译 node 原生包,适用于 electron renderer
mfsu: {
development : {
output : "./.mfsu-dev",
},
production : {
output : "./mfsu-prod",
}
}

mock

  • Type: object
  • Default: {}

配置 mock 属性。

包含以下子属性:

  • exclude,格式为 Array(string),用于忽略不需要走 mock 的文件

nodeModulesTransform

  • Type: object
  • Default: { type: 'all' }

设置 node_modules 目录下依赖文件的编译方式。

子配置项包含:

  • type,类型,可选 allnone
  • exclude,忽略的依赖库,包名,暂不支持绝对路径

两种编译模式,

  • 默认是 all,全部编译,然后可以通过 exclude 忽略不需要编译的依赖库;
  • 可切换为 none,默认值编译 es5-imcompatible-versions 里声明的依赖,可通过 exclude 配置添加额外需要编译的;

前者速度较慢,但可规避常见的兼容性等问题,后者反之。

outputPath

  • Type: string
  • Default: dist

指定输出路径。

注意:

  • 不允许设定为 srcpublicpagesmockconfig 等约定目录

plugins

  • Type: Array(string)
  • Default: []

配置额外的 dumi 插件。

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

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

插件的参数平级的配置项声明,比如:

export default {
plugins: ['umi-plugin-hello'],
hello: {
name: 'foo',
},
};

配置项的名字通常是插件名去掉 umi-plugin-@umijs/plugin 前缀。

polyfill

  • Type: { imports: string[] }

设置按需引入 polyfill,对应 core-js 的引入范围,默认全量引入。

只引入稳定功能:

export default {
polyfill: {
imports: [
'core-js/stable',
]
}
}

或自行按需引入:

export default {
polyfill: {
imports: [
'core-js/features/promise/try',
'core-js/proposals/math-extensions'
]
},
}

注意:

  • 设置 BABEL_POLYFILL=none 环境变量后,该配置失效,且无 polyfill 引入。

postcssLoader

  • Type: object
  • Default: {}

设置 postcss-loader 配置项

presets

  • Type: Array(string)
  • Default: []

plugins 配置,用于配置额外的 dumi 插件集。

proxy

  • Type: object
  • Default: {}

配置代理能力。

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

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

注意:proxy 配置仅在 dev 时生效。

publicPath

  • Type: publicPath
  • Default: /

配置 webpack 的 publicPath。当打包的时候,webpack 会在静态文件路径前面添加 publicPath 的值,当你需要修改静态文件地址时,比如使用 CDN 部署,把 publicPath 的值设为 CDN 的值就可以。如果使用一些特殊的文件系统,比如混合开发或者 cordova 等技术,可以尝试将 publicPath 设置成 ./ 相对路径。

相对路径 ./ 有一些限制,例如不支持多层路由 /foo/bar,只支持单层路径 /foo

如果你的应用部署在域名的子路径上,例如 https://www.your-app.com/foo/,你需要设置 publicPath/foo/,如果同时要兼顾开发环境正常调试,你可以这样配置:

import { defineConfig } from 'dumi';
export default defineConfig({
publicPath: process.env.NODE_ENV === 'production' ? '/foo/' : '/',
});

runtimeHistory

  • Type: object

配置是否需要动态变更 history 类型。

设置 runtimeHistory 后,可以在运行时动态修改 history 类型。

import { setCreateHistoryOptions } from 'dumi';
setCreateHistoryOptions({
type: 'memory',
});

runtimePublicPath

  • Type: boolean
  • Default: false

配置是否启用运行时 publicPath。

通常用于一套代码在不同环境有不同的 publicPath 需要,然后 publicPath 由服务器通过 HTML 的 window.publicPath 全局变量输出。

启用后,打包时会额外加上这一段,

__webpack_public_path__ = window.resourceBaseUrl || window.publicPath;

然后 webpack 在异步加载 JS 等资源文件时会从 window.resourceBaseUrlwindow.publicPath 里开始找。

ssr

  • Type: object
  • Default: false

配置是否开启服务端渲染,配置如下:

{
// 一键开启
ssr: {
// 更多配置
// forceInitial: false,
// removeWindowInitialProps: false
// devServerRender: true,
// mode: 'string',
// staticMarkup: false,
}
}

配置说明:

  • forceInitial:客户端渲染时强制执行 getInitialProps 方法,常见的场景:静态站点希望每次访问时保持数据最新,以客户端渲染为主。
  • removeWindowInitialProps: HTML 中移除 window.getInitialProps 变量,避免 HTML 中有大量数据影响 SEO 效果,场景:静态站点
  • devServerRender:在 dumi dev 开发模式下,执行渲染,用于 dumi SSR 项目的快速开发、调试,服务端渲染效果所见即所得,同时我们考虑到可能会与服务端框架(如 Egg.jsExpressKoa)结合做本地开发、调试,关闭后,在 dumi dev 下不执行服务端渲染,但会生成 umi.server.js(dumi SSR 服务端渲染入口文件),渲染开发流程交由开发者处理。
  • mode:渲染模式,默认使用 string 字符串渲染,同时支持流式渲染 mode: 'stream',减少 TTFB(浏览器开始收到服务器响应数据的时间) 时长。
  • staticMarkup:html 上的渲染属性(例如 React 渲染的 data-reactroot),常用于静态站点生成的场景上。

注意:

  • 开启后,执行 dumi dev 时,访问 http://localhost:8000 ,默认将单页应用(SPA)渲染成 html 片段,片段可以通过开发者工具『显示网页源代码』进行查看。
  • 执行 dumi build,产物会额外生成 umi.server.js 文件,此文件运行在 Node.js 服务端,用于做服务端渲染,渲染 html 片段。
  • 如果应用没有 Node.js 服务端,又希望生成 html 片段做 SEO(搜索引擎优化),可以开启 exportStatic 配置,会在执行 dumi build 构建时进行预渲染
  • removeWindowInitialPropsforceInitial 不可同时使用

了解更多,可点击 服务端渲染文档

scripts

  • Type: Array
  • Default: []

headScripts,配置 <body> 里的额外脚本。

styleLoader

  • Type: object

启用并设置 style-loader 配置项,用于让 CSS 内联打包在 JS 中,不输出额外的 CSS 文件。

styles

  • Type: Array(string)
  • Default: []

配置额外 CSS。

比如:

export default {
styles: [`body { color: red; }`, `https://a.com/b.css`],
};

会生成 HTML,

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

targets

  • Type: object
  • Default: { chrome: 49, firefox: 64, safari: 10, edge: 13, ios: 10 }

配置需要兼容的浏览器最低版本,会自动引入 polyfill 和做语法转换。

比如要兼容 ie11,需配置:

export default {
targets: {
ie: 11,
},
};

注意:

  • 配置的 targets 会和合并到默认值,不需要重复配置
  • 子项配置为 false 可删除默认配置的版本号

terserOptions

配置压缩器 terser 的配置项

theme

  • Type: object
  • Default: {}

配置主题,实际上是配 less 变量。

比如:

export default {
theme: {
// 修改 dumi 默认主题的主色,更多变量详见:https://github.com/umijs/dumi/blob/1.x/packages/theme-default/src/style/variables.less
'@c-primary': '#1DA57A',
},
};

webpack5

  • Type: object
  • Default: false

使用 webpack 5 代替 webpack 4 进行构建。

物理缓存功能默认开启,可通过设置环境变量 WEBPACK_FS_CACHEnone 来禁用。

包含以下子配置项:

  • lazyCompilation,是否启用基于路由的按需编译

workerLoader

  • Type: object
  • Default: false

开启 worker-loader 功能。