Node.js / 系统课时
管理环境变量
管理环境变量
环境变量适合把端口、运行环境和密钥等“部署时才确定”的值从源码中移出。本课用 Node.js 自带的 process.env 与 --env-file 完成开发/生产配置分离,并加入启动时校验,确保缺少关键变量时立即失败,而不是运行到业务请求时才暴露问题。
学习目标
- 读取并理解
process.env中字符串类型的环境变量。 - 用不同
.env文件区分开发与生产配置,并避免提交敏感值。 - 在应用启动阶段校验必需变量,给出明确错误。
先把配置入口收敛到 process.env
Node.js 不会自动替你设置 NODE_ENV;它只是行业常用约定。读取环境变量时还要注意:存在的值通常都是字符串,例如 PORT=3000 读到的是 "3000",缺失变量则是 undefined。因此不要在业务代码里到处直接读取,而是先集中转换和校验。
// 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
});先直接运行:
API_BASE_URL=https://dev-api.example.test NODE_ENV=development PORT=3001 node app.js预期输出:
{
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。例如准备两个文件,真实生产密钥应由部署平台注入;这里的示例只放非敏感占位值。
# .env.development
NODE_ENV=development
PORT=3001
API_BASE_URL=https://dev-api.example.test# .env.production.example
NODE_ENV=production
PORT=8080
API_BASE_URL=https://api.example.com开发环境启动:
node --env-file=.env.development app.js预期输出:
{
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。
# .gitignore
.env
.env.*
!.env.example# .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、私钥等字段只验证“是否存在”,不要记录原值。这样开发、测试与生产可以使用同一份源码,差异全部由部署环境提供。