Node.js / 系统课时

管理环境变量

管理环境变量

环境变量适合把端口、运行环境和密钥等“部署时才确定”的值从源码中移出。本课用 Node.js 自带的 process.env 与 --env-file 完成开发/生产配置分离,并加入启动时校验,确保缺少关键变量时立即失败,而不是运行到业务请求时才暴露问题。

学习目标

  • 读取并理解 process.env 中字符串类型的环境变量。
  • 用不同 .env 文件区分开发与生产配置,并避免提交敏感值。
  • 在应用启动阶段校验必需变量,给出明确错误。

先把配置入口收敛到 process.env

Node.js 不会自动替你设置 NODE_ENV;它只是行业常用约定。读取环境变量时还要注意:存在的值通常都是字符串,例如 PORT=3000 读到的是 "3000",缺失变量则是 undefined。因此不要在业务代码里到处直接读取,而是先集中转换和校验。

js
// app.js
const required = ["API_BASE_URL"];

for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
}

const nodeEnv = process.env.NODE_ENV ?? "development";
const port = Number.parseInt(process.env.PORT ?? "3000", 10);

if (!Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error("PORT must be an integer from 1 to 65535");
}

console.log({
  nodeEnv,
  port,
  apiBaseUrl: process.env.API_BASE_URL
});

先直接运行:

bash
API_BASE_URL=https://dev-api.example.test NODE_ENV=development PORT=3001 node app.js

预期输出:

text
{
  nodeEnv: 'development',
  port: 3001,
  apiBaseUrl: 'https://dev-api.example.test'
}

如果省略 API_BASE_URL,进程会在启动阶段抛出 Missing required environment variable: API_BASE_URL。这种“启动即失败”比在请求处理中得到模糊的网络错误更容易定位。

用 --env-file 分开开发与生产配置

Node.js 20.6.0 及以上可使用 --env-file 从文件加载环境变量,不必为了基础场景额外安装 dotenv。例如准备两个文件,真实生产密钥应由部署平台注入;这里的示例只放非敏感占位值。

text
# .env.development
NODE_ENV=development
PORT=3001
API_BASE_URL=https://dev-api.example.test
text
# .env.production.example
NODE_ENV=production
PORT=8080
API_BASE_URL=https://api.example.com

开发环境启动:

bash
node --env-file=.env.development app.js

预期输出:

text
{
  nodeEnv: 'development',
  port: 3001,
  apiBaseUrl: 'https://dev-api.example.test'
}

生产环境不要把真实密钥写进镜像或仓库。更常见的做法是在容器平台、CI/CD 或系统服务中注入 DATABASE_URL、API_TOKEN 等值,再直接执行 node app.js。

环境变量从部署输入到应用配置的读取与校验流程

让仓库只保存模板,不保存秘密

.gitignore 应忽略本地环境文件,同时保留一份只列变量名和安全示例值的 .env.example,让团队成员知道项目需要哪些配置。不要把真实 Token、数据库密码或私钥写进 .env.example。

text
# .gitignore
.env
.env.*
!.env.example
text
# .env.example
NODE_ENV=development
PORT=3000
API_BASE_URL=https://dev-api.example.test
API_TOKEN=

片段示例:以上是 .gitignore 与环境变量模板,不是可执行程序。验证时运行 git status --ignored,本地 .env.development 应显示为被忽略,而 .env.example 仍可正常纳入版本控制。

处理覆盖优先级与敏感日志

使用 --env-file 时,如果同名变量已经存在于进程环境中,应把部署平台注入的值视为更高优先级来源;发布前用实际 Node.js 版本验证启动行为。配置代码也不要执行 console.log(process.env),否则 CI 日志、错误日志或监控系统可能永久保存密钥。

可以把可公开字段单独打印,例如启动时只记录 NODE_ENV、PORT、服务版本;对 API_TOKEN、DATABASE_URL、私钥等字段只验证“是否存在”,不要记录原值。这样开发、测试与生产可以使用同一份源码,差异全部由部署环境提供。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理环境变量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通