node配置环境变量是什么、为什么用、在哪里、如何使用及最佳实践

【node配置环境变量】是什么？

在 Node.js 应用的开发和部署过程中，配置管理是一个核心环节。环境变 量（Environment Variables）就是一种常见的、强大且灵活的配置方式。

简单来说，环境变量是操作系统提供给运行在其上的进程（例如你的 Node.js 应用）的一组键值对。这些变量独立于你的应用代码本身，但在应用启动时或运行时可以被应用访问到。

对于 Node.js 应用而言，这些操作系统层面的环境变量会被 Node.js 进程继承，并通过全局对象 process.env 暴露出来。例如，如果你的操作系统设置了一个名为 MY_VAR 的环境变量，其值为 'some_value'，那么在你的 Node.js 代码中，你可以通过 process.env.MY_VAR 来获取这个值。

请注意，通过 process.env 访问到的所有环境变量值都将是字符串类型。即使你设置了一个看似数字的环境变量（例如 PORT=3000），在 Node.js 中访问 process.env.PORT 时，你得到的是字符串 "3000"，而不是数字 3000。

【node配置环境变量】为什么用？

使用环境变量来配置 Node.js 应用有诸多好处，主要解决以下问题：

• 环境差异化配置： 你的应用在开发环境、测试环境和生产环境可能有不同的配置需求。例如：
  • 数据库连接字符串不同。
  • 后端 API 地址不同。
  • 日志级别不同。
  • 监听的端口号不同。

  通过环境变量，你可以在不修改代码的情况下，根据当前运行的环境设置不同的配置值。

• 敏感信息管理： 密码、API 密钥、访问令牌等敏感信息不应该直接写死在代码中，更不应该被提交到版本控制系统（如 Git）。环境变量提供了一个安全的方式来在运行时将这些敏感信息注入到应用中。
• 提高灵活性和可移植性： 将配置与代码分离，使得你的应用代码更加纯粹，更容易在不同的环境中部署和运行。部署人员或运维人员只需要根据目标环境设置相应的环境变量即可。

【node配置环境变量】在哪里设置和读取？

环境变量可以在多个层面进行设置，而 Node.js 应用则通过一个统一的方式读取它们。

设置环境变量的地方：

• 操作系统/Shell 级别：
  • 在 Linux/macOS bash/zsh 中：使用 export VAR_NAME=value 命令。这通常只在当前终端会话中有效。
  • 在 Windows 命令提示符 (cmd) 中：使用 set VAR_NAME=value 命令。
  • 在 Windows PowerShell 中：使用 $env:VAR_NAME="value" 命令。
  • 你也可以将这些命令添加到 Shell 的启动脚本中（如 .bashrc, .zshrc, .profile）使其永久生效（对新开的终端会话）。
• 进程启动命令中：
  • 在 Linux/macOS 中，可以在运行 Node.js 命令时在其前面加上环境变量设置：VAR_NAME=value node your_app.js。这种方式设置的环境变量只对当前启动的 node 进程及其子进程有效。
  • 在 Windows 中，使用 set VAR_NAME=value & node your_app.js (cmd) 或 $env:VAR_NAME="value"; node your_app.js (PowerShell)。
• 使用 `.env` 文件（配合库）：
  • 这是 Node.js 开发中非常流行的一种方式，尤其适合本地开发环境。
  • 你可以在项目根目录下创建一个名为 .env 的文件，并在其中以 VAR_NAME=value 的格式列出环境变量。
  • 然后，在你的 Node.js 应用入口文件的顶部（例如 index.js 或 app.js），使用像 dotenv 这样的库来加载这些变量到 process.env 中。
  • 这种方式的好处是集中管理本地配置，并且可以轻松通过 .gitignore 文件忽略 .env 文件，避免将本地配置或敏感信息提交到版本库。
• 部署平台/CI/CD 工具中：
  • 大多数现代部署平台（如 Heroku, Vercel, Netlify, Docker Swarm, Kubernetes, AWS Elastic Beanstalk, PM2 等）都提供了界面或配置文件的方式来设置应用的运行时环境变量。
  • 在 CI/CD 流水线中，你也可以在构建或部署步骤中设置临时的环境变量。

Node.js 应用读取环境变量的方式：

• 无论环境变量是通过何种方式设置的（操作系统、进程启动、`.env` 文件加载等），一旦 Node.js 进程启动并加载了这些变量，它们都会被挂载到全局的 process.env 对象上。
• 你的 Node.js 代码只需要通过 process.env.VAR_NAME 就可以访问到对应的环境变量值。

【node配置环境变量】“多少”变量？

关于环境变量的“数量”或“容量”：

• 数量： 环境变量的数量通常受到操作系统或 Shell 的限制，而不是 Node.js 本身。理论上，你可以设置很多环境变量，但在实践中，数量过多会使得管理复杂，并且可能达到操作系统的某些限制（例如，一个进程可以拥有的环境变量总数或总大小）。保持环境变量的数量精简，只包含必要的配置，是一个好的实践。
• 容量： 单个环境变量的值的长度也受到操作系统或 Shell 的限制。通常，它们是设计用来存储短字符串（如路径、端口号、简单的标志、短密钥）的，而不是大量数据（如整个文件内容、大型 JSON 对象）。如果需要传递大量配置或数据，考虑使用配置文件、数据库或其他存储方式。

总而言之，环境变量适用于存储非敏感、环境相关的配置，以及少量敏感的密钥信息（在使用 `.env` 文件时要特别注意 `.gitignore`，生产环境应使用更安全的密钥管理方案）。不要滥用环境变量来存储大量或复杂的数据。

【node配置环境变量】如何使用及怎么管理（最佳实践）？

了解了什么是、为什么用、在哪里设置环境变量之后，最关键的就是如何在 Node.js 应用中有效地使用和管理它们。

如何在 Node.js 代码中读取环境变量：

如前所述，使用 process.env 对象：

const port = process.env.PORT;
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY;

console.log(‘应用端口:’, port);
console.log(‘数据库地址:’, dbUrl);

需要再次强调：process.env 中的所有值都是字符串。

const timeout = process.env.REQUEST_TIMEOUT; // 假设设置的是 REQUEST_TIMEOUT=5000
console.log(typeof timeout); // 输出 ‘string’
console.log(timeout + 1000); // 输出 ‘50001000’ (字符串拼接)

如何处理环境变量的类型转换：

由于环境变量值是字符串，当你需要数字、布尔值或其他类型时，必须手动进行转换。

const port = parseInt(process.env.PORT, 10); // 转换为整数
if (isNaN(port)) {
  console.error(‘错误: PORT 环境变量不是一个有效的数字’);
  process.exit(1);
}
console.log(typeof port); // 输出 ‘number’

// 处理布尔值，通常约定 ‘true’, ‘1’, ‘yes’ 等为真
const enableFeature = process.env.ENABLE_FEATURE === ‘true’;
console.log(typeof enableFeature); // 输出 ‘boolean’

如何处理缺失的环境变量：

如果代码试图访问一个未设置的环境变量，process.env.VAR_NAME 将返回 undefined。应用程序应该能够优雅地处理这种情况。

• 提供默认值： 对于非强制要求或有合理默认值的配置，可以使用逻辑 OR (||) 或空值合并运算符 (??) 提供默认值。

  const port = process.env.PORT || 3000; // 如果 PORT 未设置或为空字符串，使用 3000
  const requestTimeout = process.env.REQUEST_TIMEOUT ?? ‘5000’; // 如果 REQUEST_TIMEOUT 是 null 或 undefined，使用 ‘5000’

• 强制要求并检查： 对于应用正常运行所必需的环境变量（如数据库连接、API 密钥），应该在应用启动初期进行检查，如果缺失则抛出错误并终止应用。

  const requiredVar = process.env.REQUIRED_VARIABLE;
  if (!requiredVar) {
    console.error(‘致命错误: 必需的环境变量 REQUIRED_VARIABLE 未设置!’);
    process.exit(1); // 非零退出码表示异常退出
  }

使用 dotenv 库简化本地开发：

dotenv 是一个零依赖的库，它可以从项目根目录的 .env 文件中加载环境变量到 process.env。

安装 dotenv：

npm install dotenv

或

yarn add dotenv

创建 .env 文件（示例）：

在项目根目录创建 .env 文件。

PORT=5000
NODE_ENV=development
DATABASE_URL=mongodb://localhost:27017/mydb_dev
API_KEY=local_dev_api_key_12345
FEATURE_FLAG_ENABLED=true

在应用入口文件加载 dotenv：

通常在你的主文件（如 app.js, server.js, index.js）的顶部尽早调用 config() 方法。

require(‘dotenv’).config(); // 这一行应该尽可能早地执行

const port = process.env.PORT; // 现在可以正常访问 .env 中的变量了
const nodeEnv = process.env.NODE_ENV;
const dbUrl = process.env.DATABASE_URL;

console.log(`应用运行在 ${nodeEnv} 环境，监听端口 ${port}`);
console.log(`连接数据库: ${dbUrl}`);

// … 应用的其他代码

使用 .gitignore 忽略 .env 文件：

在你的 .gitignore 文件中添加一行，确保 .env 文件不被提交到 Git 仓库。

# .gitignore 文件
.env

这使得团队成员可以在本地拥有自己的 .env 文件，而不会相互影响，并且保障了敏感信息不被版本控制。

管理不同环境的配置：

对于开发、测试和生产环境，配置往往不同。虽然可以在各个环境中设置 Shell 环境变量，但使用文件管理更方便。一种常见的做法是使用不同的 `.env` 文件，例如 `.env.development`, `.env.production`。

可以通过 Node.js 代码根据 NODE_ENV 环境变量加载不同的 `.env` 文件：

// 在应用入口文件顶部
const env = process.env.NODE_ENV || ‘development’; // 默认开发环境
require(‘dotenv’).config({ path: `.env.${env}` });

// 现在 process.env 中加载的是 .env.development 或 .env.production 中的变量

然后，在启动生产环境应用时，设置 NODE_ENV=production node your_app.js。

Node.js 配置环境变量的最佳实践总结：

1. 配置与代码分离： 永不将环境相关的配置或敏感信息硬编码在代码中。
2. 使用环境变量： 将所有环境相关的配置项都通过环境变量注入。
3. `.env` 文件用于本地开发： 使用 dotenv 库和 .env 文件来管理本地开发环境的配置，并务必将其添加到 .gitignore。
4. 生产环境使用平台提供的机制： 在生产部署时，利用部署平台、容器编排工具或 CI/CD 工具提供的安全方式来设置环境变量，而不是依赖 `.env` 文件。这些平台通常有更安全的变量管理方式。
5. 命名规范： 环境变量名称通常使用大写字母和下划线（如 DATABASE_URL, API_KEY）。可以使用应用名作为前缀（如 MYAPP_PORT）避免冲突。
6. 类型转换和验证： 永远记住环境变量的值是字符串。在应用启动早期就完成必需的类型转换和值校验，对于缺失的关键变量要及时报错退出。
7. 敏感信息安全： 永远不要将敏感信息（如生产数据库密码、私钥）提交到代码仓库。即使在 `.env` 文件中管理本地敏感信息，也要确保 `.env` 文件被忽略。生产环境应使用更高级的密钥管理服务（如 HashiCorp Vault, AWS Secrets Manager, Azure Key Vault 等）。
8. 文档化： 在项目的 README 文件或其他文档中清晰地列出应用需要哪些环境变量，它们的用途，以及示例值（非敏感的示例）。

遵循这些实践，可以帮助你构建更安全、更灵活、更容易部署和维护的 Node.js 应用。