Nevermind

process.env.UNDEFINEDに別れを：型安全な環境変数をプロジェクトに導入する

5 分

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を第一に設計されたスキーマ宣言・検証ライブラリである。環境変数の型安全性という問題を解決するのに適している。

戦略は次のとおりだ：

  1. すべての環境変数に対するZodスキーマを定義する。
  2. アプリケーションの起動時に、そのスキーマで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ファイル自体が環境変数の信頼できるドキュメントとなり、すべての検証ロジックも一か所にまとまる。
  • 信頼できる実行環境：環境変数のタイプミス、欠落、形式の誤りによる実行時バグを防ぐ。
  • Fail-Fast：設定上の問題をデプロイや開発の最初の段階で発見できる。

結論

環境変数の検証をアプリケーションの起動時へ前倒しし、Zodのようなツールで型安全性を保証することは、費用対効果の非常に高いエンジニアリング手法である。アプリケーションの堅牢性と開発者の自信を大きく高められるため、現代のTypeScriptプロジェクトに欠かせない要素だ。

TypeScript Zod 環境変数 ベストプラクティス