Node.js项目如何配置.env环境变量

Node.js项目经常需要数据库地址、接口密钥、端口号、日志级别、第三方服务地址和运行环境标识。如果把这些配置直接写进代码，本地、测试和生产环境就很难区分，密钥也容易被提交到仓库。Node.js.env的作用，是把随环境变化的配置放到独立文件或部署平台变量中，让代码保持一致。

.env不是绝对安全的保险箱。它只是配置管理方式。更稳妥的做法是：本地开发使用.env，仓库只提交.env.example，生产环境通过平台环境变量注入，日志中不打印敏感值。

设计.env文件结构

项目根目录可以放.env文件，内容采用KEY=value格式。例如PORT=3000、NODE_ENV=development、DATABASE_URL=…。变量名建议使用大写字母和下划线，含义要清楚。

不要在.env中写复杂逻辑，也不要把大段JSON塞进单个变量。配置越简单，部署时越容易维护。不同环境可以使用.env.local、.env.test或部署平台变量，但加载顺序必须清楚。

仓库中应提交.env.example，用于说明项目需要哪些变量。真实.env应加入.gitignore。例如.env.example可写DATABASE_URL=、OPENAI_API_KEY=、LOG_LEVEL=info，但不要填真实密钥。

新成员拿到项目后，复制.env.example为.env，再填入本地配置。这样既能降低泄露风险，也能让配置项可见。

Node.js读取环境变量通常使用process.env.KEY。如果项目使用dotenv，可以在入口文件尽早加载配置。加载后，代码就能通过process.env.PORT、process.env.DATABASE_URL获取值。

不要在多个文件里重复加载dotenv。更稳妥的做法是创建配置模块，统一读取、校验并导出配置。当某个变量缺失时，应用应在启动阶段直接报错，而不是运行到一半才失败。

环境变量最常见的问题是漏填、拼错和格式错误。建议在应用启动时检查必填变量。数据库地址为空时直接停止启动，端口不是数字时给出明确错误。

数字和布尔值不要直接相信字符串。false在字符串中仍然是非空值，可能导致判断错误。可以写解析函数，把true、false、数字端口和列表变量转换成明确类型。

生产部署更推荐使用平台提供的环境变量管理能力，例如云平台、容器编排、CI/CD密钥或进程管理工具。这样可以在不改代码的情况下调整配置，并减少密钥文件落盘风险。

如果确实需要在服务器上使用.env文件，应限制文件权限，不要放到可公开访问目录，不要通过聊天截图传播，也不要把备份包上传到公开位置。

如果应用读取不到变量，先确认dotenv是否在入口文件最早加载，.env是否位于正确目录，变量名大小写是否一致，启动命令的工作目录是否正确。部署环境中还要确认平台变量是否保存并重新部署。

本地正常、线上异常，通常是生产变量缺失或值格式不同。可以打印变量是否存在的布尔状态，但不要打印完整密钥。

问：Node.js.env文件可以提交到Git吗？

不建议提交真实.env。应提交.env.example，并把.env加入.gitignore。

问：生产环境也要用dotenv吗？

不一定。很多平台可以直接注入环境变量，应用通过process.env读取即可。

问：环境变量读取到的数字为什么是字符串？

环境变量默认都是字符串，需要在配置模块中显式转换。

问：密钥泄露后怎么办？

立即撤销旧密钥，生成新密钥，并检查提交记录和日志中是否仍有泄露内容。