环境变量

概述

Node.js 在初始化期间会检查特定的环境变量，并使用它们来配置其运行时行为的各个方面。有些变量影响核心功能，如模块加载、性能设置和调试功能，而其他变量则控制 HTTP、加密或工作线程等特定子系统。

下图显示了 Node.js 启动过程中环境变量的处理方式

来源： src/node_options.cc71-74 lib/internal/process/pre_execution.js823-836

核心环境变量

NODE_OPTIONS

NODE_OPTIONS 是一个特殊的环境变量，它允许你指定在启动 Node.js 时要使用的命令行选项。选项之间用空格分隔。

出于安全和操作原因，并非所有命令行标志都可以通过 NODE_OPTIONS 设置。只有特定的标志子集才允许使用。

来源： src/node_options.cc305-308 doc/api/cli.md71-74

NODE_OPTIONS 中允许的选项

下表显示了可以在 NODE_OPTIONS 环境变量中使用的命令行选项

类别	选项
模块系统	`--conditions`, `--input-type`, `--require`, `--import`
诊断	`--trace-deprecation`, `--trace-warnings`, `--trace-env`, `--trace-exit`
性能	`--max-old-space-size`, `--heap-prof`, `--cpu-prof`
调试	`--inspect`, `--inspect-brk`, `--inspect-port`
安全	`--disable-proto`, `--disallow-code-generation-from-strings`
环境	`--env-file`, `--preserve-symlinks`, `--enable-source-maps`

来源： doc/api/cli.md73-74 test/parallel/test-process-env-allowed-flags-are-documented.js24-29

NODE_PATH

NODE_PATH 定义了 Node.js 在使用 require() 时查找模块的附加目录。目录之间应该用 : (POSIX) 或 ; (Windows) 分隔。

虽然 NODE_PATH 仍然可用，但它被认为是遗留的。现代 Node.js 应用程序应该使用 node_modules 目录和 npm/package.json 来进行模块管理。

来源： doc/api/cli.md74

NODE_ENV

虽然 Node.js 核心不直接处理 NODE_ENV，但它是许多 Node.js 框架和库用于确定应用程序运行环境的约定。常见的值包括：

值	典型用法
`development`	开发环境，启用了调试功能
`production`	生产环境，进行了优化
`test`	测试环境，用于运行测试

请注意，NODE_ENV 是一种约定，而非 Node.js 的内置功能，但它对 Express、React、Vue 等框架的行为有显著影响。

子系统的环境变量

HTTP 和网络

来源： lib/internal/process/pre_execution.js156-168

可变	描述
`HTTP_PROXY`, `http_proxy`	设置要使用的 HTTP 代理
`HTTPS_PROXY`, `https_proxy`	设置要使用的 HTTPS 代理
`NO_PROXY`, `no_proxy`	应绕过代理的主机列表，用逗号分隔
`NODE_USE_ENV_PROXY`	当设置为 `1` 时，启用代理环境变量的使用

SSL/TLS 和加密

对于支持 OpenSSL 的 Node.js，有几个环境变量会影响加密操作

可变	描述
`NODE_EXTRA_CA_CERTS`	附加 CA 证书文件的路径
`SSL_CERT_DIR`	包含受信任证书的目录
`SSL_CERT_FILE`	包含受信任证书的文件
`NODE_TLS_REJECT_UNAUTHORIZED`	当设置为 `0` 时，允许不安全的 TLS 连接（不推荐用于生产环境）

来源： src/node_options.h345-346

调试与诊断

以下环境变量对于调试和诊断 Node.js 应用程序很有用

可变	描述
`NODE_DEBUG`	要调试的核心模块列表，用逗号分隔
`NODE_DEBUG_NATIVE`	启用原生 C++ 模块的调试
`NODE_REDIRECT_WARNINGS`	将进程警告重定向到的文件
`NODE_DISABLE_COLORS`	当设置为 `1` 时，禁用 REPL 中的颜色

性能与内存

与 Node.js 性能和内存管理相关的环境变量

可变	描述
`NODE_OPTIONS="--max-old-space-size=xxxx"`	旧代堆的最大大小（以 MB 为单位）
`NODE_HEAP_PROF_NAME`	堆分析文件的名称模式
`NODE_CPU_PROF_NAME`	CPU 分析文件的名称模式

环境变量文件支持

Node.js v20.6.0 引入了对使用 --env-file 标志从文件加载环境变量的支持。此功能与环境变量相关，因为它提供了一种加载它们的机制。

来源： doc/api/cli.md822-878

环境变量文件使用简单的格式

# Comments start with #
PORT=3000
DEBUG=true  # Inline comments also allowed
MULTI_LINE="This is a
multi-line value"

在使用 shell 环境变量和环境变量文件的同时，shell 变量具有更高的优先级。您可以指定多个环境变量文件，后面的文件将覆盖前面文件的变量。

与配置文件集成

在 Node.js v23.10.0 中，通过 --experimental-config-file 标志增加了对配置文件的实验性支持。此系统根据以下优先级与环境变量进行交互：

命令行选项（最高优先级）
NODE_OPTIONS 环境变量
配置文件选项
Dotenv NODE_OPTIONS（最低优先级）

来源： doc/api/cli.md913-963

权限模型中的环境变量

Node.js v20.0.0 引入了一个权限模型，该模型使用命令行标志来限制对某些 API 的访问。这些标志可以在 NODE_OPTIONS 环境变量中提供，从而允许通过环境变量配置权限。

权限标志	描述
`--permission`	启用权限系统
`--allow-fs-read`	允许文件系统读取访问
`--allow-fs-write`	允许文件系统写入访问
`--allow-child-process`	允许创建子进程
`--allow-worker`	允许工作线程
`--allow-addons`	允许原生插件
`--allow-wasi`	允许 WASI 模块

来源： doc/api/cli.md76-184 src/node_options.cc489-513

与 Node.js 运行时架构的关系

环境变量系统在初始化和操作过程中与多个 Node.js 子系统进行交互

来源： src/node_options.cc36-41 lib/internal/process/pre_execution.js45-154

全局环境变量访问

在 Node.js 应用程序中，可以通过 process.env 对象访问环境变量，这是一个全局可供所有模块使用的对象。

这与配置 Node.js 本身的环境变量不同，但它为 Node.js 应用程序提供了一种标准化的方式来访问其执行环境。

最佳实践

在 Node.js 中处理环境变量时

谨慎使用 NODE_OPTIONS，并仅用于特定于开发的设置
不要在版本控制中的环境变量中存储 API 密钥和密码等敏感信息（请使用适当的密钥管理系统）
考虑在本地开发中使用环境变量文件的支持
记录您的应用程序使用的环境变量
当环境变量未设置时，提供合理的默认值
在应用程序中使用 dotenv 类库进行更高级的环境变量处理

兼容性考虑因素

环境变量行为可能因 Node.js 版本而异

功能	引入于	备注
`--env-file` 支持	v20.6.0	从文件加载环境变量
`--env-file-if-exists`	v22.9.0	如果文件存在，则加载环境变量文件，如果不存在则不报错
权限模型标志	v20.0.0	控制对 API 的访问
环境变量配置接口	v21.0.0+	对环境变量进行更程序化的访问

来源： doc/api/cli.md806-877 doc/changelogs/CHANGELOG_V20.md75-113