Rsbuild 支持在构建过程中向代码中注入环境变量或表达式,这对于区分运行环境、替换常量值等场景很有帮助。
本章节将介绍如何在 Rsbuild 中使用环境变量。
Rsbuild 默认通过 source.define 向代码中注入以下环境变量,它们会在构建时被替换为指定的值:
import.meta.env
包含以下环境变量:
process.env
包含以下环境变量:
你可以在 client 代码中使用 import.meta.env.MODE
来读取 mode 配置项的值。
在开发模式,以上代码会被编译为:
在生产模式,以上代码会被编译为:
在代码压缩过程中,if (false) { ... }
会被识别为无效代码,并被自动移除。
当 mode 为 'development'
时,值为 true
,否则为 false
。
当 mode 为 'production'
时,值为 true
,否则为 false
。
你可以在 client 代码中使用 import.meta.env.BASE_URL
来访问服务端的基础路径,它由 server.base 配置项决定,这有助于在代码中引用 public 目录 下的资源。
比如,我们通过 server.base 配置,将服务端的基础路径设置为 /foo
:
此时,public 目录下 favicon.ico
文件的访问 URL 为 http://localhost:3000/foo/favicon.ico
,在 JS 文件中可以使用 import.meta.env.BASE_URL
来拼接 URL:
你可以在 client 代码中使用 import.meta.env.ASSET_PREFIX
来访问静态资源的前缀。
assetPrefix
尾部的斜线符号,以便于进行字符串拼接。比如,我们通过 output.copy 配置,将 static/icon.png
图片拷贝到 dist
目录下:
此时,我们可以在 client 代码中通过以下方式来拼接图片 URL:
在开发模式,以上代码会被编译为:
在生产模式,以上代码会被编译为:
Rsbuild 也允许使用 process.env.BASE_URL
,它是 import.meta.env.BASE_URL 的别名。
例如,在 HTML 模板中,可以使用 process.env.BASE_URL
来拼接 URL:
Rsbuild 也允许使用 process.env.ASSET_PREFIX
,它是 import.meta.env.ASSET_PREFIX 的别名。
例如,在 HTML 模板中,可以使用 process.env.ASSET_PREFIX
来拼接 URL:
默认情况下,Rsbuild 会自动设置 process.env.NODE_ENV
环境变量,在开发模式为 'development'
,生产模式为 'production'
。
你可以在 Node.js 和 client 代码中直接使用 process.env.NODE_ENV
。
在开发模式,以上代码会被编译为:
在生产模式,以上代码会被编译为:
在代码压缩过程中,if (false) { ... }
会被识别为无效代码,并被自动移除。
.env
文件当项目根目录存在 .env
文件时,Rsbuild CLI 会自动使用 dotenv 来加载这些环境变量,并添加到当前 Node.js 进程中,其中的 public 变量 会被暴露在 client
代码中。
你可以通过 import.meta.env.[name]
或 process.env.[name]
来访问这些环境变量。
Rsbuild 支持读取以下 env 文件:
文件名 | 描述 |
---|---|
.env |
在所有场景下默认加载。 |
.env.local |
.env 文件的本地用法,需要添加到 .gitignore 中。 |
.env.development |
当 process.env.NODE_ENV 为 'development' 时读取。 |
.env.production |
当 process.env.NODE_ENV 为 'production' 时读取。 |
.env.development.local |
.env.development 文件的本地用法,需要添加到 .gitignore 中。 |
.env.production.local |
.env.production 文件的本地用法,需要添加到 .gitignore 中。 |
如果同时存在上述的多个文件,那么多个文件都会被读取,并且表格下方的文件具有更高的优先级。
Rsbuild 也支持读取 .env.[mode]
和 .env.[mode].local
文件,你可以通过 CLI 的 --env-mode <mode>
选项来指定 env 模式。
比如,指定 env 模式为 test
:
Rsbuild 会依次读取以下文件:
--env-mode
选项的优先级高于 process.env.NODE_ENV。
推荐使用 --env-mode
来指定 env 模式,不建议修改 process.env.NODE_ENV。
默认情况下,.env
文件位于项目的根目录。你可以通过 CLI 的 --env-dir <dir>
选项来指定 env 目录。
比如,指定 env 目录为 config
:
这种情况下,Rsbuild 会读取 ./config/.env
等 env 文件。
比如创建 .env
文件并添加以下内容:
然后在 rsbuild.config.ts
文件中,你可以通过 import.meta.env.[name]
或 process.env.[name]
访问到上述环境变量:
此时在创建 .env.local
文件,添加以下内容:
此时 BAR
的值被覆盖为 '2'
:
如果你没有使用 Rsbuild 的 CLI,而是使用了 Rsbuild 的 JavaScript API,那么你需要手动调用 Rsbuild 提供的 loadEnv 方法来读取环境变量,并通过 source.define 配置项注入到代码中。
所有以 PUBLIC_
开头的环境变量可以在 client 代码中访问,比如定义了以下变量:
在 client 代码中,你可以通过 import.meta.env.PUBLIC_*
或 process.env.PUBLIC_*
访问这些环境变量,Rsbuild 会匹配标识符替换为相应的值。
public 变量会替换 client 代码中的标识符,替换范围包含:
.js
,.ts
,.tsx
等。注意,public 变量不会替换以下文件中的标识符:
.css
, .scss
, .less
等。Rsbuild 提供了 loadEnv 方法,可以把任何前缀的环境变量注入到 client 代码中。
比如将一个 Create React App 项目迁移到 Rsbuild 时,你可以通过以下方式来读取 REACT_APP_
开头的环境变量,并通过 source.define 配置项注入:
通过 source.define 选项,你可以在构建时将代码中的全局标识符替换成其它值或者表达式。
define
类似于其它一些语言提供的宏定义能力,它常用于在构建时向代码注入环境变量等信息。
define 最基础的用途是在构建时替换代码中的全局标识符。
例如环境变量 NODE_ENV
的值会影响许多第三方模块的行为,在构建线上应用的产物时通常需要将它设置为 "production"
:
需要注意的是这里提供的值必须是 JSON 字符串,例如 process.env.NODE_ENV
的值为 "production"
则传入的值应当是 "\"production\""
才能够正确被处理。
同理 { foo: "bar" }
也应该被转换成 "{\"foo\":\"bar\"}"
,如果直接传入原始对象则意味着把标识符 process.env.NODE_ENV.foo
替换为标识符 bar
。
source.define
的具体行为请参考 API 文档。
以上例子中的环境变量 NODE_ENV
已经由 Rsbuild 自动注入,通常你不需要手动配置它的值。
需要注意的是,source.define
只能匹配完整的全局标识符,你可以将它理解为一个文本替换的过程。
如果代码里的标识符与 define
里定义的 key 不是完全相同的,Rsbuild 将无法替换它。
在使用 source.define
时,请避免替换整个 process.env
对象,比如下面的用法是不推荐的:
如果你采用了上述用法,将会导致如下问题:
process.env
代码都会被替换为完整的环境变量对象,导致前端代码的包体积增加,性能降低。因此,请按照实际需求来注入 process.env
上的环境变量,避免全量替换。
当你在 TypeScript 代码中访问环境变量时,TypeScript 可能会提示该变量缺少类型定义,此时你需要添加相应的类型声明。
比如你引用了一个 PUBLIC_FOO
变量,在 TypeScript 文件中会出现如下提示:
此时,你可以在项目中创建 src/env.d.ts
文件,并添加以下内容:
你可以像这样来扩展 import.meta.env
的类型:
如果缺少 process.env
的类型,请安装 @types/node 依赖:
然后扩展 process.env
的类型:
define
还可以用于标记死代码以协助 Rspack 进行 tree shaking 优化。
例如通过将 import.meta.env.LANGUAGE
替换为具体值来实现针对不同语言的产物进行差异化构建:
对于一段国际化代码:
指定环境变量 LANGUAGE=zh
并执行构建,得到的产物会移除多余的代码:
未用到的组件不会被打包,它们的外部依赖也会对应地被移除,最终可以得到体积更小的构建产物。