Skip to content

Commit 42d8145

Browse files
authored
docs(builder): add process.env injection guide (#3686)
1 parent 0ce52ad commit 42d8145

File tree

2 files changed

+43
-1
lines changed

2 files changed

+43
-1
lines changed

packages/document/builder-doc/docs/en/guide/advanced/define.md

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ In the production environment, the above code will be compiled as:
7474
const Image = <img src={`https://example.com/static/icon.png`} />;
7575
```
7676

77-
# Using define config
77+
## Using define config
7878

7979
By configuring the [source.define](/en/api/config-source.html#sourcedefine), you can replace expressions with other expressions or values in compile time.
8080

@@ -106,6 +106,27 @@ For more about `source.define`, just refer to [API References](/api/config-sourc
106106
The environment variable `NODE_ENV` shown in the example above is already injected by the Builder, and you usually do not need to configure it manually.
107107
:::
108108

109+
### process.env Injection
110+
111+
When using `source.define` or `source.globalVars`, please avoid injecting the entire `process.env` object, e.g. the following usage is not recommended:
112+
113+
```js
114+
export default {
115+
source: {
116+
define: {
117+
'process.env': JSON.stringify(process.env),
118+
},
119+
},
120+
};
121+
```
122+
123+
If the above usage is adopted, the following problems will be caused:
124+
125+
1. Some unused environment variables are additionally injected, causing the environment variables of the development environment to be leaked into the front-end code.
126+
2. As each `process.env` code will be replaced by a complete environment variable object, the bundle size of the front-end code will increase and the performance will decrease.
127+
128+
So please avoid full injection, just inject the used variables from `process.env`.
129+
109130
## Setup Environment Variables
110131

111132
You may often need to set environment variables, in which case you can instead use the [source.globalVars](/en/api/config-source.html#sourceglobalvars) configuration to simplify configuration. It is a syntax sugar of `source.define`, the only difference is that `source.globalVars` will automatically stringify the value, which makes it easier to set the value of global variables and avoid writing a lot of `JSON.stringify(...)` stuffs.

packages/document/builder-doc/docs/zh/guide/advanced/define.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,27 @@ export default {
106106
以上例子中的环境变量 `NODE_ENV` 已经由 Builder 自动注入,通常你不需要手动配置它的值。
107107
:::
108108

109+
### process.env 注入方式
110+
111+
在使用 `source.define``source.globalVars` 时,请避免注入整个 `process.env` 对象,比如下面的用法是不推荐的:
112+
113+
```js
114+
export default {
115+
source: {
116+
define: {
117+
'process.env': JSON.stringify(process.env),
118+
},
119+
},
120+
};
121+
```
122+
123+
如果你采用了上述用法,将会导致如下问题:
124+
125+
1. 额外注入了一些未使用的环境变量,导致开发环境的环境变量被泄露到前端代码中。
126+
2. 由于每一处 `process.env` 代码都会被替换为完整的环境变量对象,导致前端代码的包体积增加,性能降低。
127+
128+
因此,请按照实际需求来注入 `process.env` 上的环境变量,避免全量注入。
129+
109130
## 设置环境变量
110131

111132
针对设置环境变量的高频场景,Builder 还提供了 [source.globalVars](/api/config-source.html#sourceglobalvars) 配置用于简化配置,它是 `source.define` 的一个语法糖,唯一的区别是 `source.globalVars` 会自动将传入的值进行 JSON 序列化处理,这使得设置环境变量的值更容易,避免大量书写 `JSON.stringify(...)` 转换语句:

0 commit comments

Comments
 (0)