环境变量配置

dumi 可以通过环境变量来完成一些特殊的配置和功能。

如何设置环境变量

执行命令时设置

例如需要改变 dumi dev 开发服务器的端口，可以通过如下命令实现。

# OS X, Linux
$ PORT=3000 dumi dev

# Windows (cmd.exe)
$ set PORT=3000&&dumi dev

如果需要同时在不同的操作系统中使用环境变量，推荐使用工具 cross-env。

$ pnpm install cross-env -D
$ cross-env PORT=3000 dumi dev

设置在 .env 文件中

如果你的环境变量需要在开发者之间共享，推荐你设置在项目根目录的 .env 文件中，例如:

# file .env
PORT=3000
DUMI_CACHE=none

然后执行，

$ dumi dev

dumi 会以 3000 端口启动 dev server，并且禁用 dumi 的缓存。

如果你有部分环境变量的配置在本地要做特殊配置，可以配置在 .env.local 文件中去覆盖 .env 的配置。比如在之前的 .env 的基础上, 你想本地开发覆盖之前 3000 端口, 而使用 4000 端口，可以做如下定义。

# file .env.local
PORT=4000

dumi 会以 4000 端口启动 dev server，同时保持禁用 dumi 的缓存。

此外 dumi .env 文件中还支持变量的方式来配置环境变量。例如：

# file .env.local
FOO=foo
BAR=bar

CONCAT=$FOO$BAR # CONCAT=foobar

dumi 不支持 .env.development / .env.production 的环境变量配置文件，如需在不同的环境下有不同的变量值，请使用 cross-env 在不同的启动命令上区分，或定义在各个 DUMI_ENV 对应的 dumi 配置文件内。

注意：

• 不建议将 .env.local 加入版本管理中。

在浏览器中使用环境变量

所有通过 .env 环境变量文件 或 命令行注入 的环境变量均默认只在 dumi 配置文件 (Node.js 环境) 内生效，在浏览器中无法直接通过 process.env.VAR_NAME 方式使用，通过进一步配置 define 来注入到浏览器环境中：

# .env
MY_TOKEN="xxxxx"

// .umirc.ts

  define: { 'process.env.MY_TOKEN': process.env.MY_TOKEN }

注：我们约定所有以 DUMI_APP_ 开头的环境变量会默认注入到浏览器中，无需配置 define 手动注入。

环境变量列表

按字母顺序排列。

APP_ROOT

指定项目根目录。

注意：

• APP_ROOT 不能配在 .env 中，只能在命令行里添加

ANALYZE

用于分析 bundle 构成，默认关闭。

比如：

$ ANALYZE=1 dumi dev
# 或者
$ ANALYZE=1 dumi build

可以通过 ANALYZE_PORT 环境变量自定义端口或 analyze 选项自定义配置。

BABEL_POLYFILL

默认会根据 targets 配置打目标浏览器的全量补丁，设置为 none 禁用内置的补丁方案。

COMPRESS

默认压缩 CSS 和 JS，值为 none 时不压缩，build 时有效。

ERROR_OVERLAY

设置为 none 会禁用「Error Overlay」，在调试 Error Boundary 时会有用。

FS_LOGGER

默认会开启保存物理日志，值为 none 时不保存，同时针对 webcontainer 场景（比如 stackbliz）暂不保存。

HMR

默认开启 HMR 功能，值为 none 时关闭。

HOST

默认是 0.0.0.0。

PORT

指定端口号，默认是 8000。

SOCKET_SERVER

指定用于 HMR 的 socket 服务器。比如：

$ SOCKET_SERVER=http://localhost:8000/ dumi dev

SPEED_MEASURE

分析 Webpack 编译时间，支持 CONSOLE 和 JSON 两种格式，默认是 CONSOLE。

$ SPEED_MEASURE=JSON dumi dev

DUMI_ENV

当指定 DUMI_ENV 时，会额外加载指定值的配置文件，优先级为：

• .dumirc.ts

• .dumirc.${DUMI_ENV}.ts

• .dumirc.${dev | prod | test}.ts

• .dumirc.${dev | prod | test}.${DUMI_ENV}.ts

• .dumirc.local.ts

若不指定 DUMI_ENV ，则只会加载当前环境对应的配置文件，越向下的越具体，优先级更高，高优的配置可以往下移动。

注：根据当前环境的不同，dev, prod, test 配置文件会自动加载，不能将 DUMI_ENV 的值设定成他们。

DUMI_PLUGINS

指定 dumi 命令执行时额外加载的插件的路径，使用 , 隔开。

$ DUMI_PLUGINS=./path/to/plugin1,./path/to/plugin2  dumi dev

DUMI_PRESETS

指定 dumi 命令执行时额外加载插件集的路径，使用 , 隔开。

$ DUMI_PRESETS=./path/to/preset1,./path/to/preset2  dumi dev

DUMI_DEV_SERVER_COMPRESS

默认 dumi 开发服务器自带 compress 压缩中间件，这会使开发时 SSE 数据的传输 无法流式获取 ，通过指定 DUMI_DEV_SERVER_COMPRESS=none 来关闭 compress 压缩功能：

DUMI_DEV_SERVER_COMPRESS=none dumi dev

WEBPACK_FS_CACHE_DEBUG

开启 webpack 的物理缓存 debug 日志。

$ WEBPACK_FS_CACHE_DEBUG=1 dumi dev

DUMI_CACHE

默认会将框架的高消耗执行结果（例如编译 Markdown 文件）持久化存储到本地，该结果会在二次执行时被选择性复用以提升框架运行速度，设置为 none 时可以禁用该行为，通常用于开发自定义 Markdown 插件的调试环节。

DUMI_THEME

指定主题包路径，优先级高于项目 package.json 中声明的 dumi-theme-xx 主题包依赖；该路径下存在主题包 package.json 和 dist 产物，通常用于 dumi 插件强制指定主题包或基于 dumi 二次开发的场景，非前述场景不建议使用。

$ DUMI_THEME=./path/to/theme1 dumi dev