你如何在 Node 中管理配置和机密？

Question

你如何在 Node 中管理配置和机密？

Accepted Answer

配置（数据库 URL、API 密钥、端口、功能开关）应该存放在代码**外部**的环境变量中——绝不要硬编码。这样可以将机密信息保持在源代码控制之外，让同样的代码在开发、预发布和生产环境中以不同的设置运行。

## 原则：从环境中获取配置

```js
// ❌ NEVER hardcode secrets — they end up in git history forever
const dbUrl = "postgres://admin:password123@db.example.com";

// ✅ read from the environment
const dbUrl = process.env.DATABASE_URL;
const port = process.env.PORT || 3000;
```

这遵循**十二因子应用**原则：配置与代码严格分离，因此部署到新环境只需更改环境变量，而不是代码。

## 本地开发：.env 文件

```bash
# .env — local values, GITIGNORED (never committed)
DATABASE_URL=postgres://localhost/myapp_dev
JWT_SECRET=dev-secret
PORT=3000
```

```js
// load .env into process.env (older: dotenv; newer Node: --env-file flag)
import "dotenv/config";        // or: node --env-file=.env app.js
const secret = process.env.JWT_SECRET;
```

`.env` 文件保存本地配置；它**必须被加入 gitignore**。提交一个 `.env.example`（包含键但没有真实值）来记录所需的内容。

## 在启动时验证配置

```js
import { z } from "zod";

const env = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(16),
  PORT: z.coerce.number().default(3000),
}).parse(process.env); // ❗ fail FAST at startup if config is missing/invalid
```

在启动时验证环境变量（使用 zod/envalid）意味着缺少或格式错误的机密信息会立即导致崩溃并显示清晰的消息——远好于请求深处令人困惑的运行时失败。

## 生产环境中的机密

```text
Dev:        .env file (gitignored)
Production: injected by the platform/orchestrator —
            cloud secret managers (AWS Secrets Manager, GCP Secret Manager, Vault),
            container/orchestrator env vars, CI/CD secrets.
Never put production secrets in .env files committed or shipped with the app.
```

## 集中化访问

```js
// config.js — one validated config module the app imports (don't sprinkle process.env everywhere)
export const config = { dbUrl: env.DATABASE_URL, port: env.PORT };
```

## 为什么这很重要

恰当的配置和机密管理既是**安全**要求，也是**运维**必需。

硬编码机密会将它们泄露到版本控制中（一个严重的常见漏洞）；将配置混入代码中会让跨环境部署变得痛苦。

标准方法——环境变量、本地开发时使用 gitignored 的 `.env` 文件、用于文档的 `.env.example`、启动时验证，以及生产环境中使用平台机密管理器——可以保持机密安全、使应用在环境之间可移植，并及早发现配置错误。

这是负责任地运行 Node 应用的基础。