Node.js v25.3.0 文档

CLI 环境变量#>

【CLI Environment Variables】

有一组环境变量可以被定义来定制 Node.js 的行为，更多详情请参考 CLI 环境变量文档。

【There is a set of environment variables that can be defined to customize the behavior of Node.js, for more details refer to the CLI Environment Variables documentation.】

process.env#>

与环境变量交互的基本 API 是 process.env，它由一个对象组成，该对象包含预先填充的用户环境变量，并且可以进行修改和扩展。

【The basic API for interacting with environment variables is process.env, it consists of an object with pre-populated user environment variables that can be modified and expanded.】

有关更多详细信息，请参阅process.env 文档。

【For more details refer to the process.env documentation.】

环境变量配置#>

【DotEnv】

用于处理在 .env 文件中定义的附加环境变量的工具集。

【Set of utilities for dealing with additional environment variables defined in .env files.】

.env 文件#>

【.env files】

.env 文件（也称为 dotenv 文件）是用于定义环境变量的文件，Node.js 应用可以与之交互（由 dotenv 包推广）。

以下是一个基本 .env 文件内容的示例：

【The following is an example of the content of a basic .env file:】

MY_VAR_A = "my variable A"
MY_VAR_B = "my variable B" 拷贝

这种类型的文件在各种不同的编程语言和平台中都有使用，但没有正式的规范，因此 Node.js 定义了其自己的规范，如下所述。

【This type of file is used in various different programming languages and platforms but there is no formal specification for it, therefore Node.js defines its own specification described below.】

.env 文件是一个包含键值对的文件，每个键值对由变量名、等号（=）以及变量值组成。

【A .env file is a file that contains key-value pairs, each pair is represented by a variable name followed by the equal sign (=) followed by a variable value.】

此类文件的名称通常为 .env，或者以 .env 开头（例如 .env.dev，其中 dev 表示特定的目标环境）。这是推荐的命名方式，但不是强制要求，dotenv 文件可以有任何任意的文件名。

【The name of such files is usually .env or it starts with .env (like for example .env.dev where dev indicates a specific target environment). This is the recommended naming scheme but it is not mandatory and dotenv files can have any arbitrary file name.】

变量名称#>

【Variable Names】

有效的变量名只能包含字母（大写或小写）、数字和下划线（_），且不能以数字开头。

【A valid variable name must contain only letters (uppercase or lowercase), digits and underscores (_) and it can't begin with a digit.】

更具体地说，有效的变量名必须符合以下正则表达式：

【More specifically a valid variable name must match the following regular expression:】

^[a-zA-Z_]+[a-zA-Z0-9_]*$ 拷贝

推荐的惯例是使用大写字母、下划线以及在必要时使用数字，但任何符合上述定义的变量名都可以正常使用。

【The recommended convention is to use capital letters with underscores and digits when necessary, but any variable name respecting the above definition will work just fine.】

例如，以下是一些有效的变量名：MY_VAR、MY_VAR_1、my_var、my_var_1、myVar、My_Var123，而以下这些则无效：1_VAR、'my-var'、"my var"、VAR_#1。

【For example, the following are some valid variable names: MY_VAR, MY_VAR_1, my_var, my_var_1, myVar, My_Var123, while these are instead not valid: 1_VAR, 'my-var', "my var", VAR_#1.】

变量值#>

【Variable Values】

变量的值可以由任意文本组成，可选择性地用单引号（'）或双引号（"）括起来。

【Variable values are comprised by any arbitrary text, which can optionally be wrapped inside single (') or double (") quotes.】

带引号的变量可以跨多行，而不带引号的变量则限制为一行。

【Quoted variables can span across multiple lines, while non quoted ones are restricted to a single line.】

注意，当由 Node.js 解析时，所有值都会被解释为文本，这意味着任何值都会在 Node.js 中成为一个 JavaScript 字符串。例如，以下值：0、true 和 { "hello": "world" } 将分别变为字面字符串 '0'、'true' 和 '{ "hello": "world" }'，而不是数字 0、布尔值 true 和带有 hello 属性的对象。

【Noting that when parsed by Node.js all values are interpreted as text, meaning that any value will result in a JavaScript string inside Node.js. For example the following values: 0, true and { "hello": "world" } will result in the literal strings '0', 'true' and '{ "hello": "world" }' instead of the number zero, the boolean true and an object with the hello property respectively.】

有效变量示例：

【Examples of valid variables:】

MY_SIMPLE_VAR = a simple single line variable
MY_EQUALS_VAR = "this variable contains an = sign!"
MY_HASH_VAR = 'this variable contains a # symbol!'
MY_MULTILINE_VAR = '
this is a multiline variable containing
two separate lines\nSorry, I meant three lines' 拷贝

间距#>

【Spacing】

除非用引号括起来，否则变量键和值周围的前后空白字符会被忽略。

【Leading and trailing whitespace characters around variable keys and values are ignored unless they are enclosed within quotes.】

例如：

【For example:】

   MY_VAR_A   =    my variable a
    MY_VAR_B   =    '   my variable b   ' 拷贝

将被视为与以下情况相同：

【will be treated identically to:】

MY_VAR_A = my variable a
MY_VAR_B = '   my variable b   ' 拷贝

注释#>

【Comments】

井号（#）字符表示注释的开始，这意味着该行的其余部分将被完全忽略。

【Hash-tag (#) characters denote the beginning of a comment, meaning that the rest of the line will be completely ignored.】

引号内的井号将被视为任何其他标准字符。

【Hash-tags found within quotes are however treated as any other standard character.】

例如：

【For example:】

# This is a comment
MY_VAR = my variable # This is also a comment
MY_VAR_A = "# this is NOT a comment" 拷贝

export 前缀#>

【export prefixes】

export 关键字可以选择性地添加在变量声明前，该关键字在文件的所有处理过程中都会被完全忽略。

【The export keyword can optionally be added in front of variable declarations, such keyword will be completely ignored by all processing done on the file.】

这很有用，因为可以在 shell 终端中获取文件而无需修改。

【This is useful so that the file can be sourced, without modifications, in shell terminals.】

示例：

【Example:】

export MY_VAR = my variable 拷贝

CLI 选项#>

【CLI Options】

.env 文件可以通过以下 CLI 选项之一来填充 process.env 对象：

• --env-file=file
• --env-file-if-exists=file

编程 API#>

【Programmatic APIs】

以下两个函数允许你直接与 .env 文件进行交互：

【There following two functions allow you to directly interact with .env files:】

• process.loadEnvFile 会加载 .env 文件，并使用其中的变量填充 process.env
• util.parseEnv 解析 .env 文件的行内容，并以对象的形式返回其值