如何在 Node.js 项目中使用 .env 环境变量

在 Node.js 项目中使用 .env文件来管理环境变量是一种非常常见且推荐的做法。最主流和简单的方法是使用 dotenv这个 npm 包。

1. 安装 dotenv

首先，在你的项目根目录下，通过 npm 或 yarn 安装它：

npm install dotenv
# 或者
yarn add dotenv

2. 创建 `.env`文件

在你的项目根目录下创建一个名为 .env的文件。

重要：

这个文件绝对不能提交到版本控制系统（如 Git）中。你必须将 .env添加到你的 .gitignore文件中，以防止敏感信息（如数据库密码、API 密钥）泄露。
文件名必须以点开头。

3. 在 `.env`文件中定义变量

在 .env文件中，你可以以 KEY=VALUE的格式定义你的环境变量。不要使用引号（''或 ""），不要在等号两边留空格（虽然有时有空格也能工作，但最佳实践是不留）。

示例 .env文件内容：

# 数据库连接配置
DB_HOST=localhost
DB_PORT=5432
DB_NAME=my_database
DB_USER=admin
DB_PASSWORD=super_secret_password

# 第三方 API 密钥
API_KEY=abcdef123456
SENDGRID_USERNAME=your_username
SENDGRID_PASSWORD=your_password

# 应用设置
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

4. 在代码中尽早加载和读取配置

在你的 Node.js 应用程序的入口文件（通常是 app.js, index.js或 server.js）的最顶部，引入并配置 dotenv。

dotenv的 config()方法会读取 .env文件，将其中的变量解析并注入到 Node.js 的 process.env对象中。

示例代码：

// 在入口文件的最顶部加载环境变量配置
require('dotenv').config();

// 现在你可以从 process.env 中访问你定义的变量了
const express = require('express');
const app = express();
const port = process.env.PORT || 3000; // 使用环境变量中的 PORT，如果没有则默认为 3000

app.get('/', (req, res) => {
  res.send('Hello World!');
});

// 例如，连接数据库时使用
const { Pool } = require('pg');
const pool = new Pool({
  user: process.env.DB_USER,
  host: process.env.DB_HOST,
  database: process.env.DB_NAME,
  password: process.env.DB_PASSWORD,
  port: process.env.DB_PORT,
});

app.listen(port, () => {
  console.log(`示例应用正在监听端口 ${port}`);
  console.log(`当前环境是: ${process.env.NODE_ENV}`);
});

高级用法和最佳实践

1. 为不同环境创建不同的 `.env`文件

你可以创建多个环境配置文件，例如：

.env.development(开发环境)
.env.production(生产环境)
.env.staging(预发布环境)

然后，你可以在运行程序时通过 NODE_ENV环境变量来指定加载哪个文件。这通常通过在 package.json的脚本中传递参数来实现。

修改你的入口文件代码：

// 根据 NODE_ENV 决定加载哪个 .env 文件
const path = require('path');
require('dotenv').config({
  path: path.resolve(process.cwd(), `.env.${process.env.NODE_ENV}`),
});

// 如果 NODE_ENV 未设置，则 fallback 到默认的 .env 文件
// 或者更常见的做法：开发环境用 .env，生产环境在服务器上直接设置变量

在 package.json中配置脚本：

{
  "scripts": {
    "dev": "NODE_ENV=development nodemon app.js",
    "start": "NODE_ENV=production node app.js"
  }
}

注意：在 Windows 命令行中设置 NODE_ENV的语法不同，通常使用 set NODE_ENV=development。推荐使用 cross-env包来跨平台设置环境变量，或者使用 Windows 的 PowerShell/WSL。

2. 生产环境注意事项

在生产环境中，通常不建议使用 .env文件。 相反，你应该直接在运行应用程序的环境中设置这些变量。这是更安全、更标准的方式。

Linux/macOS (Bash): export DB_PASSWORD=super_secret_password
使用 PM2: 可以在 ecosystem file 中定义 env变量。
使用 Docker: 通过 -e标志传递或在 docker-compose.yml中定义。
云平台 (Heroku, AWS, Vercel 等): 都在其管理后台提供了设置环境变量的界面。

在这种情况下，process.env会直接读取系统环境变量，而 dotenv不会覆盖它们。这意味着你的代码无需修改即可同时适应开发（使用 .env文件）和生产（使用系统环境变量）环境。

3. 添加 `.env.example`文件

为了帮助其他开发者了解你的项目需要哪些环境变量，你应该在版本库中保留一个 .env.example文件。这个文件列出了所有需要的变量键名，但不包含具体的敏感值。

示例 .env.example：

# 将此文件复制并重命名为 .env，然后填写你的实际值
DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=
API_KEY=
NODE_ENV=development
PORT=

新克隆项目的开发者只需要执行 cp .env.example .env，然后填写实际值即可。

如何在 Node.js 项目中使用 .env 环境变量

1. 安装 dotenv

2. 创建 .env文件

3. 在 .env文件中定义变量