Node.js v24.5.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 files (also known as dotenv files) are files that define environment variables, which Node.js applications can then interact with (popularized by the dotenv package).

以下是基本 .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" }'（而非数字零）、布尔值 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 treaded identically to:

MY_VAR_A = my variable
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 files can be used to populate the process.env object via one the following CLI options:

• --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 中

  ¥process.loadEnvFile loads an .env file and populates process.env with its variables

• util.parseEnv 解析 .env 文件的行内容并将其值返回到对象中

  ¥util.parseEnv parses the row content of an .env file and returns its value in an object