编译时配置

dumi 2 基于 Umi 4，除了自身特有的配置项以外，同样也支持 Umi 4 提供的基础配置项，两者均在 .dumirc.ts 中配置。

// .dumirc.ts
import { defineConfig } from 'dumi';

export default defineConfig({
  ...
});

重点配置项

resolve

用于配置 Markdown 解析相关的行为，包含如下子项。

docDirs

• 类型：string[]
• 默认值：['docs']

配置 Markdown 文档的解析目录，路径下的 Markdown 文档会根据目录结构解析为路由。

atomDirs

• 类型：{ type: string; subType?: string; dir: string }[]
• 默认值：[{ type: 'component', dir: 'src' }]

配置原子资产（例如组件、函数、工具等）Markdown 的解析目录。

其中 type 用于指定资产类别，必须是 URL 友好的单数单词，比如 component 或者 hook；subType 用于指定资产的子类别，通常在需要生成二级导航时使用，值必须为 URL 友好的单词；dir 指定目录下第一层级的 Markdown 文档会被解析为该实体分类下的路由，嵌套层级将不会识别。比如在默认配置下，src/Foo/index.md 将被解析为 components/foo 的路由，type 配置值将自动被复数化后作为路由的前缀路径。

单独将资产的解析逻辑拆分是为了解决 dumi 1 中普通文档与源码目录下的组件文档混淆不清、分组困难的问题。

codeBlockMode

• 类型：'active' | 'passive'
• 默认值：'active'

配置代码块的解析模式。dumi 默认会编译有关联技术栈的代码块（比如内置的 React 技术栈会编译 jsx、tsx 代码块）、将其处理为组件，不需要编译的代码块需要添加 | pure 修饰符才能跳过编译；倘若你希望将这个行为反过来，可以将其配置为 passive。

两者在使用上的区别如下：

active 模式：

```jsx
export default () => '我会被编译，展示为组件';
```

```jsx | pure
export default () => '我不会被编译，仍然展示为源代码';
```

passive 模式：

```jsx
export default () => '我不会被编译，仍然展示为源代码';
```

```jsx | demo
export default () => '我会被编译，展示为组件';
```

entryFile

• 类型：string
• 默认值：undefined

指定项目的入口文件，比如 ./src/index.ts，目前该配置会用于 API 解析，可参考指南 - 自动 API 表格。

forceKebabCaseRouting

• 类型：boolean
• 默认值：true

配置强制 kebab-case 路由模式，即所有路径都会被转换为短横线模式，比如 HelloWorld 将会被转换为 hello-world，该配置默认开启，配置为 false 时将以实际文件路径为准。

apiParser

• 类型：{ unpkgHost?: 'https://unpkg.com'; resolveFilter?: (args: { id: string; ids: string; type: 'COMPONENT' | 'FUNCTION' }) => boolean }
• 默认值：undefined

启用 API 自动解析功能，开启后可使用 API 全局组件，参考指南 - 自动 API 表格。

其中 unpkgHost 配置项用于自定义 unpkg.com 的地址以加快访问速度，比如自己的私有镜像地址。解析过程中如果存在找不到的依赖，会兜底到 unpkgHost 的地址去找。

resolveFilter 配置项用于跳过指定原子资产的解析以提升性能。部分组件属性或函数签名存在多层嵌套，甚至是循环引用时，会导致解析结果巨大，此时可以通过该配置项跳过解析。

autoAlias

• 类型：boolean
• 默认值：true

是否自动 alias 项目包名到 src 目录，如果是 father 4 项目，还会根据配置自动 alias 产物目录到源码目录，默认开启。

locales

• 类型：{ id: string, name: string, base?: string }[]
• 默认值：[{ id: 'zh-CN', name: '中文' }]

配置站点的多语言，各子项释义如下：

1. id 值会作为 dumi 识别 Markdown 文件后缀的依据，以及主题国际化文案的 key。例如，值为 zh-CN 时意味着 index.zh-CN.md 的文件会被归类到该语言下
2. 对于默认语言的 Markdown 文件而言，后缀是可选的。例如，在默认配置下，index.zh-CN.md 与 index.md 等价
3. name 值会作为页面渲染语言切换链接的文本值，当只有一种语言时，不会展示切换链接
4. 约定第一项（即 locales[0]）为站点默认语言，其余为其他语言，对应页面需带上 base 才能访问到
5. base 值指定该语言的基础路由，对默认语言来说默认值为 /，对非默认语言来说默认值为 /${id}，仅在希望 id 和 base 不一致时才需要配置，且仅默认语言支持配置为 /

extraRemarkPlugins

• 类型：(string | function | [string, object] | [function, object])[]
• 默认值：[]

配置额外的 remark 插件，用于处理 Markdown 语法树的编译。数组项的值可以是：

1. 插件名称或路径
2. 插件函数
3. 传递数组时，第一项为插件名称/路径/函数，第二项为插件配置

extraRehypePlugins

• 类型：(string | function | [string, object] | [function, object])[]
• 默认值：[]

配置额外的 rehype 插件，用于处理 HTML 语法树的编译。数组项的值可以是：

1. 插件名称或路径
2. 插件函数
3. 传递数组时，第一项为插件名称/路径/函数，第二项为插件配置

analytics

• 类型：{ ga_v2?: string; baidu?: string; ga?: string }
• 默认值：undefined

dumi 内置了站点统计的功能，目前支持 Google Analytics 和百度统计。

示例：

{
  analytics: {
    // google analytics 的 key (GA 4)
    ga_v2: 'G-abcdefg',
    // 若你在使用 GA v1 旧版本，请使用 `ga` 来配置
    ga: 'ga_old_key'

    // 百度统计的 key
    baidu: 'baidu_tongji_key',
  }
}

sitemap

• 类型：{ hostname: string, exclude?: string[] }
• 默认值：undefined

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

html2sketch2.2.0+

• 类型：{ scriptUrl?: string }
• 默认值：undefined

启用 HTML 转 Sketch 的功能，scriptUrl 配置项用于指定 html2sketch 的脚本地址，如果你不希望使用内置的 CDN 地址，可以选择自定义。

该功能会在 demo 预览器操作栏添加『拷贝到 Sketch』按钮，点击后会将当前 demo 转换为 Sketch 对象并复制到剪贴板，该功能基于 Ant Design - html2sketch 项目，需要注意的是，目前必须配合 Kitchen 插件才能实现在 Sketch 中粘贴，步骤演示如下：

光看演示不过瘾？不妨试试看：

主题配置项

通过 themeConfig 可配置传递给主题的配置项：

// .dumirc.ts
import { defineConfig } from 'dumi';

export default defineConfig({
  themeConfig: {
    // 主题配置项均放置在这一层
  },
});

具体可用的配置项取决于项目当前使用的主题包，dumi 的默认主题目前支持如下配置项：

editLink 2.2.2+

• 类型：boolean | string
• 默认值：true

配置是否在 Markdown 页面内容区域底部展示当前文档的编辑链接。

当配置为 true 时 dumi 会根据项目 package.json 中的 repository 配置及当前分支，使用 hosted-git-info 自动生成编辑链接，仅支持部分代码托管平台；如果你使用的是其他代码托管平台或私有化部署的平台，可以使用字符串模板自定义编辑链接，例如 https://gitlab.example.com/group/repo/{filename}，其中 {filename} 会被替换为当前文档在仓库中的文件路径。

lastUpdated 2.2.2+

• 类型：boolean
• 默认值：true

配置是否在 Markdown 页面内容区域底部展示当前文档的最后更新时间。

文档最后更新时间来源于 Git 提交记录，如果 Markdown 文档还未被 Git 追踪，那么则会展示构建时间；如果你的文档通过 GitHub Action 进行部署，还需要在 actions/checkout 步骤中加上 fetch-depth: 0 参数以检出所有 Git 提交记录，确保可以 dumi 可以拿到正确的最后更新时间，具体可参考 FAQ - 自动部署。

logo

• 类型：string | false
• 默认值：dumi 的 LOGO

配置导航栏上的站点 LOGO，如果需要配置为本地图片文件，可将图片资源放入 public 文件夹，例如放置 public/logo.png，则配置 /logo.png 即可。

配置为 false 时不展示 LOGO。

name

• 类型：string
• 默认值：undefined

配置导航栏上的站点名称，不配置时不展示。

nav

• Navs类型：{ title: '导航标题', link: '导航路由', activePath: '高亮路径' }[] | Record<string, { title: '导航标题', link: '导航路由', activePath: '高亮路径' }[]>
• 类型：Navs | {mode: "override" | "append" | "prepend", value: Navs}
• 默认值：约定式导航

配置导航栏上的导航项，不配置时默认为约定式导航。约定式导航生成规则可参考 约定式路由。

{
  // 单语言时配置数组即可
  nav: [{ title: 'Blog', link: '/blog' }],

  // 多语言时配置对象，key 为语言名
  nav: {
    'zh-CN': [{ title: '博客', link: '/blog' }],
    'en-US': [{ title: 'Blog', link: '/en/blog' }],
  },

  // 支持通过 nav 将路由追加到约定路由前面或后面
  nav: {
    // mode可选值有：override、append、prepend
    // - override: 直接覆盖约定导航，与 nav: [{ title: 'Blog', link: '/blog' }] 配置相同
    // - append: 将 value 中的导航追加到约定路由后面
    // - prepend: 将 value 中的导航添加到约定路由前面
    mode: "append",
    value: [{ title: 'Blog', link: '/blog' }]
  }
}

sidebar

• 类型：Record<'/nav_path', { title: '分组名称（可选）', children: { title: '菜单项', link: '菜单路由' }[] }[]>
• 默认值：约定式侧边菜单

配置侧边栏菜单，key 为导航路由，配置后对该导航下的所有一级子页面生效，例如 { '/guide': [] } 只对 /guide 及 /guide/xxx 生效。

不配置时默认为约定式侧边菜单，约定式侧边菜单生成规则可参考 约定式路由。

footer

• 类型：string | false
• 默认值：Powered by dumi

配置页脚内容，可以是 HTML，配置 false 时不展示。

rtl

• 类型：boolean
• 默认值：false

是否开启 RTL 切换，配置为 true 时导航栏会展示 RTL 按钮，用于将站点文本阅读方向切换为『从右到左』，通常在站点用户群体中有使用希伯来语或阿拉伯语时启用。

showLineNum 2.2.0+

• 类型：boolean
• 默认值：false

是否在代码块中展示行号，配置为 true 时会展示代码行号。

nprogress -2.1.23+

• 类型：boolean
• 默认值：true

切换页面时是否在页面顶部展示进度条，效果如 nprogress。

prefersColor

• 类型：{ default: 'light' | 'dark' | 'auto'; switch: boolean }
• 默认值：{ default: 'light', switch: true }

配置站点的主题色，其中 default 配置项为默认主题色，默认为亮色模式，配置为 auto 时将跟随用户的操作系统配置自动切换；switch 配置项控制主题色切换器的展示与否，配置为 false 时用户将无法主动切换站点主题色。

对于普通文档站点来说，建议保持 switch 的默认值 true，将站点主题色的选择权交给用户，同时可以考虑将 default 设置为 auto 以跟随用户的系统配置：

export default {
  themeConfig: {
    prefersColor: { default: 'auto' },
  },
};

对于组件库文档站点来说，建议根据组件库对暗色模式的适配情况来选择是否配置 switch 为 false，避免用户切换主题色后组件 demo 的样式出现异常。

对于主题开发者来说，可以在 Less 文件中使用 @dark-selector 的全局变量来为主题包的组件增加暗色模式的样式：

.some-container {
  // 亮色模式为白色
  color: #fff;

  // 暗色模式变黑色
  @{dark-selector} & {
    color: #000;
  }
}

socialLinks

如果想要在顶部导航栏右侧增加一些社交网站的外链图标，可以通过 socialLinks 进行配置，目前最多支持配置 5 个外链图标

目前支持以下社交平台图标：

export default {
  themeConfig: {
    socialLinks: {
      github: 'https://github.com/umijs/dumi',
      weibo: 'https://xxxx',
      twitter: 'https://xxxx',
      gitlab: 'https://xxxx',
      facebook: 'https://xxxx',
      zhihu: 'https://xxxx',
      yuque: 'https://xxxx',
      linkedin: 'https://xxxx',
    },
  },
};

基础配置项

对于 dumi 中能使用的自定义配置，你可以使用项目根目录的 .dumirc.ts 文件或者 config/config.ts，值得注意的是这两个文件功能一致，仅仅是存在目录不同，2 选 1 ，.dumirc.ts 文件优先级较高。

更多目录相关信息介绍，你可以在目录结构了解。

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

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

import { defineConfig } from 'dumi';

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

使用 defineConfig 包裹配置是为了在书写配置文件的时候，能得到更好的拼写联想支持。如果你不需要，直接 export default {} 也可以。

值得关注的是在你使用 dumi 的时候，你不需要了解每一个配置的作用。你可以大致的浏览一下以下 dumi 支持的所有配置，然后在你需要的时候，再回来查看如何启用和修改你需要的内容。

为方便查找，以下配置项通过字母排序。

alias

• 类型：Record<string, string>
• 默认值：{}

配置别名，对 import 语句的 source 做映射。

比如：

{
  alias: {
    foo: '/tmp/to/foo',
  }
}

然后代码里 import 'foo' 实际上会 import '/tmp/to/foo'。

有几个 Tip。

1、alias 的值最好用绝对路径，尤其是指向依赖时，记得加 require.resolve，比如，

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

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

2、如果不需要子路径也被映射，记得加 $ 后缀，比如

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

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

autoprefixer

• 类型：object
• 默认值：{ flexbox: 'no-2009' }

用于解析 CSS 并使用来自 Can I Use 的值将供应商前缀添加到 CSS 规则。如自动给 CSS 添加 -webkit- 前缀。

更多配置，请查阅 autoprefixer 的配置项。

analyze

• 类型：object
• 默认值：{}

通过指定 ANALYZE=1 环境变量分析产物构成时，analyzer 插件的具体配置项，见 webpack-bundle-analyzer

base

• 类型：string
• 默认值：/

要在非根目录下部署 dumi 项目时，你可以使用 base 配置。

base 配置允许你为应用程序设置路由前缀。比如有路由 / 和 /users，设置 base 为 /foo/ 后就可通过 /foo/ 和 /foo/users 访问到之前的路由。

注意：base 配置必须在构建时设置，并且不能在不重新构建的情况下更改，因为该值内联在客户端包中。

cacheDirectoryPath

• 类型：string
• 默认值：node_modules/.cache

默认情况下 dumi 会将构建中的一些缓存文件存放在 node_modules/.cache 目录下，比如 logger 日志，webpack 缓存，mfsu 缓存等。你可以通过使用 cacheDirectoryPath 配置来修改 dumi 的缓存文件目录。

示例，

// 更改缓存文件路径到 node_modules/.cache1 文件夹
cacheDirectoryPath: 'node_modules/.cache1',

chainWebpack

• 类型：(memo, args) => void
• 默认值：null

为了扩展 dumi 内置的 webpack 配置，我们提供了用链式编程的方式修改 webpack 配置，基于 webpack-chain，具体 API 可参考 webpack-api 的文档。

如下所示：

export default {
  chainWebpack(memo, args) {
    return memo;
  },
};

该函数具有两个参数：

• memo 是现有 webpack 配置
• args 包含一些额外信息和辅助对象，目前有 env 和 webpack。env 为当前环境，值为 development 或 production；webpack 为 webpack 对象，可从中获取 webpack 内置插件等

用法示例：

export default {
  chainWebpack(memo, { env, webpack }) {
    // 设置 alias
    memo.resolve.alias.set('foo', '/tmp/to/foo');

    // 添加额外插件
    memo.plugin('hello').use(Plugin, [...args]);

    // 删除 dumi 内置插件
    memo.plugins.delete('hmr');
  },
};

clickToComponent

• 类型: { editor?: string }
• 默认值: false

当前仅 React 项目支持。

开启后，可通过 Option+Click/Alt+Click 点击组件跳转至编辑器源码位置，Option+Right-click/Alt+Right-click 可以打开上下文，查看父组件。

关于参数。editor 为编辑器名称，默认为 'vscode'，支持 vscode & vscode-insiders。

配置 clickToComponent 的行为，详见 click-to-component。

示例：

// .dumirc.ts
export default {
  clickToComponent: {},
};

codeSplitting

• 类型：{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }
• 默认值：null

提供 code splitting 的策略方案。

bigVendors 是大 vendors 方案，会将 async chunk 里的 node_modules 下的文件打包到一起，可以避免重复。同时缺点是，1）单文件的尺寸过大，2）毫无缓存效率可言。

depPerChunk 和 bigVendors 类似，不同的是把依赖按 package name + version 进行拆分，算是解了 bigVendors 的尺寸和缓存效率问题。但同时带来的潜在问题是，可能导致请求较多。我的理解是，对于非大型项目来说其实还好，因为，1）单个页面的请求不会包含非常多的依赖，2）基于 HTTP/2，几十个请求不算问题。但是，对于大型项目或巨型项目来说，需要考虑更合适的方案。

granularChunks 在 bigVendors 和 depPerChunk 之间取了中间值，同时又能在缓存效率上有更好的利用。无特殊场景，建议用 granularChunks 策略。

conventionLayout

• 类型：boolean
• 默认值：undefined

src/layouts/index.[tsx|vue|jsx|js] 为约定式布局，默认开启。可通过配置 conventionLayout: false 关闭该默认行为。

conventionRoutes

• 类型：{ base: string; exclude: RegExp[] }
• 默认值：{ base: './.dumi/pages', exclude: [/(\/|^)(\.|_\/)/] }

修改默认的约定式路由规则，仅在使用 dumi 约定式路由时有效，约定式路由也叫文件路由，就是不需要手写配置，文件系统即路由，通过目录和文件及其命名分析出路由配置。

使用约定式路由时，约定 .dumi/pages 下所有的 (j|t)sx? 文件即路由。

你可以从约定式路由查看更多说明。

base

base 用于设置约定的路由的基础路径，默认从 .dumi/pages 读取，如果是文档站点可能会需要将其改成 ./docs；

exclude

你可以使用 exclude 配置过滤一些不需要的文件，比如用于过滤 components、models 等。

示例，

// 不识别 components 和 models 目录下的文件为路由
conventionRoutes: {
  exclude: [/\/components\//, /\/models\//],
}

copy

• 类型：Array<string | { from: string; to: string; }>
• 默认值：[]

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

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

copy: ['foo.json', 'src/bar.json']

会产生如下产物的结构：

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

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

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

此时将产生如下产物结构：

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

crossorigin

• 类型：{ includes?: string[] }
• 默认值：false

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

关于参数。includes 参数可以为额外的非本地 script 标签加上此属性。

比如：

crossorigin: {}

然后输出的 HTML 中会有这些变化，

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

cssMinifier

• 类型：string 可选的值：esbuild, cssnano, parcelCSS, none
• 默认值：esbuild

配置构建时使用的 CSS 压缩工具; none 表示不压缩。

示例：

{
  cssMinifier: 'esbuild'
}

cssMinifierOptions

• 类型：object
• 默认值：{}

cssMinifier CSS 压缩工具配置选项。

示例：

{
  cssMinifier: 'esbuild',
  cssMinifierOptions: {
    minifyWhitespace: true,
    minifySyntax: true,
  },
}

对应 CSS 压缩的配置请查看对应的文档。

• esbuild 参考
• cssnano 参考
• parcelCSS 参考

cssPublicPath

• 类型：string
• 默认值：./

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

cssLoader

• 类型：object
• 默认值：{}

配置 css-loader ，详见 css-loader > options

define

• 类型：Record<string, string>
• 默认值： 如下

  { 
    'process.env.NODE_ENV' : process.env.NODE_ENV,
    'process.env.HMR' : process.env.HMR, 
    'process.env.SOCKET_SERVER': process.env.ERROR_OVERLAY' 
  }

基于define-plugin 插件设置代码中的可用变量。

比如，

define: { FOO: 'bar' }

然后代码里的 console.log(hello, FOO) 会被编译成 console.log(hello, 'bar')。

当你在 ts 的项目中使用这些变量时，你需要在 typings 文件中声明变量类型，以支持 ts 类型提示，比如：

如果你的 typings 文件是全局的：

// typings.d.ts
declare const FOO: string;

如果你的 typings 文件是非全局的（包含了 import/export）：

// typings.d.ts
import './other.d.ts';

declare global {
 const FOO: string;
}

devtool

• 类型：string
• 默认值：dev 时默认 cheap-module-source-map，build 时候默认无 sourcemap

设置 sourcemap 生成方式。

常见可选值有：

• eval，最快的类型，缺点是不支持低版本浏览器
• source-map，最慢但最全的类型

示例，

// 关闭 dev 阶段的 sourcemap 生成
devtool: false;

// 只设置 dev 阶段的 sourcemap
devtool: process.env.NODE_ENV === 'development' ? 'eval' : false;

classPropertiesLoose

• 类型：object
• 默认值：{}

设置 babel class-properties 启用 loose

esbuildMinifyIIFE

• 类型：boolean
• 默认值：true

修复 esbuild 压缩器自动引入的全局变量导致的命名冲突问题。

由于 dumi 默认使用 esbuild 作为压缩器，该压缩器会自动注入全局变量作为 polyfill ，这可能会引发 异步块全局变量冲突、 qiankun 子应用和主应用全局变量冲突 等问题，通过打开该选项或切换 jsMinifier 压缩器可解决此问题。

更多信息详见 vite#7948 。

示例,

esbuildMinifyIIFE: true

externals

• 类型：Record<string, string> | Function
• 默认值：{}

设置哪些模块不打包，转而通过 <script> 或其他方式引入，通常需要搭配 headScripts 配置使用。

示例，

// external react
externals: { react: 'React' },
headScripts: ['https://unpkg.com/react@17.0.1/umd/react.production.min.js'],

注意：不要轻易设置 antd 的 externals，由于依赖较多，使用方式复杂，可能会遇到较多问题，并且一两句话很难解释清楚。

extraBabelIncludes

• 类型：Array<string | RegExp>
• 默认值：[]

配置额外需要做 Babel 编译的 NPM 包或目录。比如：

export default {
  extraBabelIncludes: [
    // 支持绝对路径
    join(__dirname, '../../common'),
    // 支持 npm 包
    'react-monaco-editor',
    // 转译全部路径含有 @scope 的包
    /@scope/
  ],
};

extraBabelPlugins

• 类型：string[] | Function
• 默认值：[]

配置额外的 babel 插件。可传入插件地址或插件函数。

extraBabelPresets

• 类型：string[] | Function
• 默认值：[]

配置额外的 babel 插件集。可传入插件集地址或插件集函数。

extraPostCSSPlugins

• 类型：PostCSSPlugin[]
• 默认值：[]

配置额外的 postcss 插件。

exportStatic

• 类型：{ extraRoutePaths: IUserExtraRoute[] | (() => IUserExtraRoute[] | Promise<IUserExtraRoute[]>), ignorePreRenderError: boolean }
• 默认值：{}

开启该配置后会针对每个路由单独输出 HTML 文件，通常用于静态站点托管。例如项目有如下路由：

/
/docs
/docs/a

不开启 exportStatic 时会输出：

dist/index.html

开启 exportStatic 时会输出：

dist/index.html
dist/docs/index.html
dist/docs/a/index.html

通过 extraRoutePaths 子配置项可以产出额外的页面，通常用于动态路由静态化。例如有如下路由：

/news/:id

默认情况下只会输出 dist/news/:id/index.html，但可以通过配置 extraRoutePaths 将其静态化：

// .dumirc.ts
export default {
  exportStatic: {
    // 配置固定值
    extraRoutePaths: ['/news/1', '/news/2'],
    // 也可以配置函数动态获取
    extraRoutePaths: async () => {
      const res = await fetch('https://api.example.com/news');
      const data = await res.json();
      return data.map((item) => `/news/${item.id}`);
    },
  },
}

此时输出文件会变成：

dist/news/:id/index.html
dist/news/1/index.html
dist/news/2/index.html

extraRoutePaths 除了支持配置字符串数据，还可以配置成对象数组，用于启用 SSR 时又希望对部分路由禁用预渲染的场景，例如：

// .dumirc.ts
export default {
  exportStatic: {
    // 输出额外页面文件但跳过预渲染
    extraRoutePaths: [{ path: '/news/1', prerender: false }],
  },
}

exportStatic 在搭配 ssr 使用时会进行预渲染，在预渲染失败时会抛出异常并终止构建，可以通过配置 ignorePreRenderError 来忽略预渲染失败的错误，例如：

// .dumirc.ts
export default {
  exportStatic: {
    // 忽略预渲染失败的错误
    ignorePreRenderError: true,
  },
}

favicons

• 类型：string[]
• 默认值：null

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

通过如下方式自定义：

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

forkTSChecker

• 类型：object
• 默认值：null

开启 TypeScript 的类型检查。基于 fork-ts-checker-webpack-plugin，配置项可参考 fork-ts-checker-webpack-plugin 的 Options。

hash

• 类型：boolean
• 默认值：true

开启 hash 模式，让 build 之后的产物包含 hash 后缀。通常用于增量发布和避免浏览器加载缓存。

启用后，产物通常是这样，

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

注意：HTML 文件始终没有 hash 后缀。

headScripts

• 类型：string[] | Script[]
• 默认值：[]

配置 <head> 中的额外 script。

比如，

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

会生成 HTML，

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

如果需要额外属性，切换到对象格式，比如，

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

history

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

设置路由 history 类型。

historyWithQuery

• 类型：‌{}
• 默认值：false

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

https

• 类型：{ cert: string; key: string; hosts: string[]; http2?: boolean }
• 默认值：{ hosts: ['127.0.0.1', 'localhost'] }

开启 dev 的 https 模式，dumi 默认使用 mkcert 快捷创建证书，请确保已经安装。

关于参数。

• cert 和 key 分别用于指定 cert 和 key 文件。
• hosts 用于指定要支持 https 访问的 host，默认是 ['127.0.0.1', 'localhost']。
• http2 用于指定是否使用 HTTP 2.0 协议，默认是 true（使用 HTTP 2.0 在 Chrome 或 Edge 浏览器中中有偶然出现 ERR_HTTP2_PROTOCOL_ERRO报错，如有遇到，建议配置为 false）。

示例，

https: {
}

ignoreMomentLocale

• 类型：boolean
• 默认值：true

忽略 moment 的 locale 文件，用于减少产物尺寸。

注意：此功能默认开。配置 ignoreMomentLocale: false 关闭。

inlineLimit

• 类型：number
• 默认值：10000 (10k)

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

jsMinifier

• 类型：string，可选值 esbuild, terser, swc, uglifyJs, none
• 默认值：esbuild

配置构建时压缩 JavaScript 的工具；none表示不压缩。

示例：

{
  jsMinifier: 'esbuild'
}

jsMinifierOptions

• 类型：object
• 默认值：{}

jsMinifier 的配置项；默认情况下压缩代码会移除代码中的注释，可以通过对应的 jsMinifier 选项来保留注释。

示例：

{
  jsMinifier: 'esbuild',
  jsMinifierOptions: {
    minifyWhitespace: true,
    minifyIdentifiers: true,
    minifySyntax: true,
  }
}

配置项需要和所使用的工具对应，具体参考对应文档：

• esbuild 参考
• terser 参考
• swc 参考
• uglifyJs 参考

lessLoader

• 类型：object
• 默认值：{ modifyVars: userConfig.theme, javascriptEnabled: true }

设置 less-loader 的 Options。具体参考参考 less-loader 的 Options。

默认是用 less@4 版本，如果需要兼容 less@3 请配置使用less-options-math。

legacy

• 类型：{ buildOnly?: boolean; nodeModulesTransform?: boolean; checkOutput?: boolean; }
• 默认值：false

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

legacy: {}

默认只在构建时生效，通过设定 buildOnly: false 关闭该限制。

可通过打开 checkOutput: true 选项，每次构建结束后将自动运行 es-check 检查产物 .js 文件的语法是否为 es5 格式。

开启此选项后：

• 不支持自定义 srcTranspiler 、jsMinifier 、 cssMinifier 选项。
• 将转译全部 node_modules 内的源码，targets 兼容至 ie 11 ，通过指定 nodeModulesTransform: false 来取消对 node_modules 的转换，此时你可以通过配置 extraBabelIncludes 更精准的转换那些有兼容性问题的包。
• 因低版本浏览器不支持 Top level await ，当你在使用 externals 时，确保你没有在使用异步性质的 externalsType 时又使用了同步导入依赖。

links

• 类型：Link[]
• 默认值：[]

配置额外的 link 标签。

示例，

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

manifest

• 类型：{ fileName: string; basePath: string }
• 默认值：null

开启 build 时生成额外的 manifest 文件，用于描述产物。

关于参数。fileName 是生成的文件名，默认是 asset-manifest.json；basePath 会给所有文件路径加上前缀。

注意：只在 build 时生成。

metas

• 类型：Meta[]
• 默认值：[]

配置额外的 meta 标签。

比如，

metas: [
  { name: 'keywords', content: 'dumi, base on dumi' },
  { name: 'description', content: 'React framework.' },
],

会生成以下 HTML，

<meta name="keywords" content="dumi, base on dumi" />
<meta name="description" content="React framework." />

mfsu

• 类型：{ esbuild: boolean; mfName: string; cacheDirectory: string; include?: string[]; chainWebpack: (memo, args) => void; exclude?: Array<string | RegExp> }
• 默认值：{ mfName: 'mf' }

配置基于 Module Federation 的提速功能。

关于参数

• esbuild 配为 true 后会让依赖的预编译走 esbuild，从而让首次启动更快，缺点是二次编译不会有物理缓存，稍慢一些；推荐项目依赖比较稳定的项目使用。
• mfName 是此方案的 remote 库的全局变量，默认是 mf，通常在微前端中为了让主应用和子应用不冲突才会进行配置
• cacheDirectory 可以自定义缓存目录，默认是 node_modules/.cache/mfsu
• chainWebpack 用链式编程的方式修改 依赖的 webpack 配置，基于 webpack-chain，具体 API 可参考 webpack-api 的文档；
• runtimePublicPath 会让修改 mf 加载文件的 publicPath 为 window.publicPath
• exclude 手动排除某些不需要被 MFSU 处理的依赖, 字符串或者正则的形式，比如 vant 不希望走 MFSU 处理，可以配置 { exclude: [ 'vant' ] } 匹配逻辑为全词匹配，也可以配置 { exclude: [ /vant/ ] } 只要 import 路径中匹配该正则的依赖都不走 MFSU 处理

示例，

// 用 esbuild 做依赖预编译
mfsu: {
  esbuild: true,
}

// 关闭 mfsu 功能
mfsu: false;

// webpack 配置修改
mfsu: {
  chainWebpack(memo, args) {
    // 添加额外插件
    memo.plugin('hello').use(Plugin, [...args]);
    return memo;
  }
}

注意：此功能默认开。配置 mfsu: false 关闭。

mock

• 类型：{ exclude: string[], include: string[] }
• 默认值：{}

配置 mock 功能。

关于参数。exclude 用于排除不需要的 mock 文件；include 用于额外添加 mock 目录之外的 mock 文件。

示例，

// 让所有 pages 下的 _mock.ts 文件成为 mock 文件
mock: {
  include: ['.dumi/pages/**/_mock.ts'],
}

注意：此功能默认开。配置 mock: false 关闭。

mountElementId

• 类型：string
• 默认值：'root'

配置 react 组件树渲染到 HTML 中的元素 id。

示例，

mountElementId: 'container'

monorepoRedirect

• 类型：{ srcDir?: string[], exclude?: RegExp[], peerDeps?: boolean, useRootProject?: boolean }
• 默认值：false

在 monorepo 中使用 dumi 时，你可能需要引入其他子包的组件、工具方法等，通过开启此选项来重定向这些子包的导入到他们的源码位置（默认为 src 文件夹），这也可以解决 MFSU 场景改动子包不热更新的问题。

这种重定向的好处是：支持热更新，无需预构建其他子包即可进行开发。

通过配置 srcDir 来调整识别源码文件夹的优先位置，通过 exclude 来设定不需要重定向的依赖范围。

示例：

// 默认重定向到子包的 src 文件夹
monorepoRedirect: {}
// 在子包中寻找，优先定向到 libs 文件夹
monorepoRedirect: {
  srcDir: ['libs', 'src'],
}
// 不重定向 @scope/* 的子包
monorepoRedirect: {
  exclude: [/^@scope\/.+/],
}

在实际的大型业务 monorepo 中，每个子包的依赖都是从他们的目录开始向上寻找 node_modules 并加载的，但在本地开发时，依赖都安装在 devDependencies ，和从 npm 上安装表现不一致，所以不可避免会遇到多实例问题。

为了解决这种问题，我们约定：

当打开 peerDeps 选项时，所有子包指明的 peerDependencies 都会被自动添加 alias 重定向唯一化，避免多实例的存在：

monorepoRedirect: { peerDeps: true }

经过重定向，依赖全局唯一，便可以在开发时保持和在 npm 上安装包后的体验一致。

useRootProject: 当你的项目不在 monorepo 子文件夹里，而在 monorepo 根的话，你可以开启这个选项，以使 monorepoRedirect 生效。

outputPath

• 类型：string
• 默认值：dist

配置输出路径。

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

plugins

• 类型：string[]
• 默认值：[]

配置额外的 dumi 插件。

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

示例，

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

polyfill

• 类型：{ imports: string[] }
• 默认值：{}

设置按需引入的 polyfill。默认全量引入。

比如只引入 core-js 的 stable 部分，

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

如果对于性能有更极致的要求，可以考虑按需引入，

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

注意：此功能默认开。配置 polyfill: false 或设置环境变量 BABEL_POLYFILL=none 关闭。

postcssLoader

• 类型：object
• 默认值：{}

设置 postcss-loader 的配置项。

presets

• 类型：string[]
• 默认值：[]

配置额外的 dumi 插件集。

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

示例，

presets: [
  // npm 依赖
  'dumi-preset-hello',
  // 相对路径
  './preset',
  // 绝对路径
  `${__dirname}/preset.js`,
],

proxy

• 类型：object
• 默认值：{}

配置代理功能。

比如，

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

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

注意：proxy 功能仅在 dev 时有效。

publicPath

• 类型：string
• 默认值：/

配置 webpack 的 publicPath。

routes

• 类型：Route[]
• 默认值：[]

配置路由。非推荐用法，暂不提供示例

routeLoader

• 类型：{ moduleType: 'esm' | 'cjs' }
• 默认值：{ moduleType: 'esm' }

配置路由加载方式。moduleType 配置为 'cjs' 会用 require 的方式加载路由组件。

// moduleType: esm
'index': React.lazy(() => import(/* webpackChunkName: "p__index" */'../../pages/index.tsx')),

// moduleType: cjs
'index': React.lazy(() => Promise.resolve(require('../../pages/index.tsx'))),

run

• 类型：{ globals: string[] }
• 默认值：null

run 命令的全局注入配置。添加['zx/globals']，在使用dumi run ./script.ts的时候，dumi会自动注入import 'zx/globals';，从而省略掉每个脚本都要写import 'zx/globals';。

runtimePublicPath

• 类型：object
• 默认值：null

启用运行时 publicPath，开启后会使用 window.publicPath 作为资源动态加载的起始路径。

比如，

runtimePublicPath: {},

scripts

• 类型：string[] | Script[]
• 默认值：[]

配置 <body> 中额外的 script 标签。

比如，

scripts: [`alert(1);`, `https://a.com/b.js`],

会生成 HTML，

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

如果需要额外属性，切换到对象格式，比如，

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

sassLoader

• 类型：object
• 默认值：{}

配置 sass-loader ，详见 sass-loader > options

styleLoader

• 类型：object
• 默认值：false

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

stylusLoader

• 类型：object
• 默认值：{}

配置 stylus-loader ，详见 stylus-loader > options

styles

• 类型：string[]
• 默认值：[]

配置额外的 CSS。

配置项支持内联样式和外联样式路径，后者通过是否以 https?:// 开头来判断。

插入的样式会前置，优先级低于项目内用户编写样式。

比如：

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

会生成以下 HTML，

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

srcTranspiler

• 类型：string 可选的值：babel, swc, esbuild
• 默认值：babel

配置构建时转译 js/ts 的工具。

srcTranspilerOptions

• 类型：{ swc?: SwcConfig, esbuild?: EsbuildConfig }
• 默认值：undefined

如果你使用了 swc / esbuild 作为 srcTranspiler 转译器，你可以通过此选项对转译器做进一步的配置，详见 SwcConfig 、 EsbuildConfig 配置文档。

如给 swc 添加其他的插件：

srcTranspilerOptions: {
  swc: {
    jsc: {
      experimental: {
        plugins: [
          [
            '@swc/plugin-styled-components',
            {
              displayName: true,
              ssr: true,
            },
          ],
        ],
      },
    },
  },
}

svgr

• 类型：object
• 默认值：{}

svgr 默认开启，支持如下方式使用 React svg 组件：

import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';

可配置 svgr 的行为，配置项详见 @svgr/core > Config。

svgo

• 类型：object
• 默认值：{}

默认使用 svgo 来优化 svg 资源，配置项详见 svgo 。

targets

• 类型：object
• 默认值：{ chrome: 80 }

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

示例，

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

theme

• 类型：object
• 默认值：{}

配置 less 变量主题。

示例：

// 修改 dumi 默认主题的主色，更多变量详见：https://github.com/umijs/dumi/blob/master/src/client/theme-default/styles/variables.less
(theme: { '@c-primary': '#1DA57A' })

title

• 类型：string
• 默认值：null

配置全局页面 title，暂时只支持静态的 Title。

writeToDisk

• 类型：boolean
• 默认值：false

开启后会在 dev 模式下额外输出一份文件到 dist 目录，通常用于 chrome 插件、electron 应用、sketch 插件等开发场景。