配置项

在项目根目录创建 .umirc.ts 或 config/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 模式下可用。

logo

类型：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.md 和 index.en-US.md 等价。

mode

类型：doc | site
默认值：doc
详细：

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

两种模式的效果如下，文档模式：

站点模式：

menus

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

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

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

navs

类型：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 目录，通常不需要配置，除非自动嗅探出现了『误伤』。

注意：

默认的 src 和 docs 目录会自动排除 node_modules 和 fixtures 目录。

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 build 或 ANALYZE=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，当前环境，development、production 或 test 等
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，值为 development 或 production

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

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: true 或 https: {} 开启，使用 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.js 和 umi.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，可选 browser、hash 和 memory
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 配置项。

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，类型，可选 all 和 none
exclude，忽略的依赖库，包名，暂不支持绝对路径

两种编译模式，

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

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

outputPath

Type: string
Default: dist

指定输出路径。

注意：

不允许设定为 src、public、pages、mock、config 等约定目录

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.resourceBaseUrl 或 window.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.js、Express、Koa）结合做本地开发、调试，关闭后，在 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 构建时进行预渲染。
removeWindowInitialProps 与 forceInitial 不可同时使用

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

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

Type: object
Default: terserOptions.ts

配置压缩器 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_CACHE 为 none 来禁用。

包含以下子配置项：

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

workerLoader

Type: object
Default: false

开启 worker-loader 功能。

dumi

配置项

基础配置

algolia

apiParser

description

logo

locales

mode

menus

navs

resolve

resolve.includes

resolve.excludes

resolve.previewLangs

resolve.passivePreview

sitemap

title

themeConfig

更多配置

404

alias

analyze

autoprefixer

base

chainWebpack

chunks

cssLoader

cssModulesTypescriptLoader

cssnano

copy

define

devServer

devtool

dynamicImport

dynamicImportSyntax

exportStatic

externals

extraBabelIncludes

extraBabelPlugins

extraBabelPresets

extraPostCSSPlugins

favicon

forkTSChecker

fastRefresh

hash

headScripts

history

ignoreMomentLocale

inlineLimit

lessLoader

links

manifest

metas

mfsu

mock

nodeModulesTransform

outputPath

plugins

polyfill

postcssLoader

presets

proxy

publicPath

runtimeHistory

runtimePublicPath

ssr

scripts

styleLoader

styles

targets

terserOptions

theme

webpack5

workerLoader