Nevermind

告别 process.env.UNDEFINED：在项目中实现类型安全的环境变量

5 min

1. process.env 的“陷阱”

在 Node.js 应用中，我们通过 process.env 来访问环境变量。这是一个简单有效的机制，但它存在一个固有的问题：类型不安全。

process.env 对象的值要么是 string，要么是 undefined。这导致了几个常见的问题：

  • 意外的 undefined: 如果你忘记在 .env 文件或服务器上设置某个变量，process.env.MY_VAR 在运行时会是 undefined，这可能在代码的深层逻辑中导致 TypeError。
  • 类型不匹配: 你可能期望一个端口号是 number 类型，但 process.env.PORT 始终是一个字符串，你需要在使用它的地方手动调用 parseInt。
  • 校验逻辑分散: 我们常常在代码的各个角落编写防御性代码，如 const port = process.env.PORT || 3000;，这使得环境变量的管理变得混乱。

2. 核心原则：启动时失败 (Fail-Fast)

对于环境变量这类关键配置，一个最佳实践是 “启动时失败” (Fail-Fast)。

这意味着，应用应该在启动的最初阶段就检查所有必需的环境变量是否都已提供且格式正确。如果存在任何问题，应用应该立即抛出错误并停止运行，而不是在未来的某个不确定时间点因为配置错误而崩溃。

这样可以让我们在部署或开发时立即发现配置问题，而不是在用户访问时。

3. 使用 Zod 实现类型安全校验

Zod 是一个以 TypeScript 为先的 schema 声明和验证库。它非常适合用来解决环境变量的类型安全问题。

我们的策略是：

  1. 为所有环境变量定义一个 Zod schema。
  2. 在应用启动时，用这个 schema 来解析 process.env。
  3. 如果解析失败（即验证不通过），Zod 会抛出一个错误，应用启动失败。
  4. 如果解析成功，我们得到一个完全类型化的对象，并在整个应用中使用它。

实现示例

首先，安装 Zod: pnpm add zod

然后，创建一个专门的文件来处理环境变量，例如 src/env.ts：

// src/env.ts
import { z } from 'zod';

// 1. 定义 Schema
const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  DATABASE_URL: z.string().min(1, 'DATABASE_URL is required.'),
  PORT: z.coerce.number().int().positive().default(3000),
  // z.coerce 会尝试将字符串转换为数字
});

// 2. 解析和导出
// .parse 会在验证失败时抛出错误，实现 "Fail-Fast"
export const env = envSchema.parse(process.env);

现在，在你的应用的其他任何地方，你都可以从 src/env 导入 env 对象。

// src/server.ts
import { env } from './env'; // 导入经过验证和类型化的 env 对象

// env.PORT 的类型是 `number`，而不是 `string | undefined`
const port = env.PORT;

// env.NODE_ENV 的类型是 'development' | 'production' | 'test'
if (env.NODE_ENV === 'development') {
  console.log('Running in development mode');
}

// 如果 DATABASE_URL 未设置，应用在启动时就已经崩溃了，
// 所以在这里我们可以放心地认为它是存在的，并且类型是 `string`。
connectToDatabase(env.DATABASE_URL);

4. 带来的好处

这种模式带来了立竿见影的好处：

  • 完全的类型安全: 在代码中访问 env.PORT 时，TypeScript 知道它是一个 number。
  • 集中的文档和校验: env.ts 文件本身就成了环境变量的权威文档，所有校验逻辑都集中于此。
  • 可靠的运行时: 杜绝了因环境变量拼写错误、缺失或格式不正确而导致的运行时 Bug。
  • “Fail-Fast”: 任何配置问题都会在部署或开发的第一时间被发现。

结论

将环境变量的校验前置到应用启动时，并使用像 Zod 这样的工具来保证其类型安全，是一个投入产出比极高的工程实践。它能显著提升应用的健壮性和开发者的信心，是现代 TypeScript 项目中不可或缺的一环。

TypeScript Zod Environment Variables Best Practices