Zod で Next.js の環境変数を起動時に検証する

概要

環境変数は process.env.FOO で参照すると string | undefined になり、未設定のまま動作し続けてしまう。 Zod で起動時に検証することで、設定漏れをビルドエラーや起動時エラーとして即検出できる。

インストール

npm install zod

実装例

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

const envSchema = z.object({
  // サーバーサイドのみ（NEXT_PUBLIC_ なし）
  DATABASE_URL: z.string().url("DATABASE_URL は有効な URL である必要があります"),
  API_SECRET_KEY: z.string().min(1, "API_SECRET_KEY が設定されていません"),

  // クライアントサイドでも使う（NEXT_PUBLIC_ 付き）
  NEXT_PUBLIC_API_BASE_URL: z.string().url("NEXT_PUBLIC_API_BASE_URL は有効な URL である必要があります"),
});

// parse に失敗すると ZodError が throw され、起動が止まる
export const env = envSchema.parse({
  DATABASE_URL: process.env.DATABASE_URL,
  API_SECRET_KEY: process.env.API_SECRET_KEY,
  NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,
});

// src/lib/api/client.ts（env を import して使う）
import { env } from "@/lib/env";

export async function apiFetch(path: string) {
  const res = await fetch(`${env.NEXT_PUBLIC_API_BASE_URL}${path}`, {
    headers: {
      Authorization: `Bearer ${env.API_SECRET_KEY}`,
    },
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

# .env.local（設定例）
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
API_SECRET_KEY=your-secret-key
NEXT_PUBLIC_API_BASE_URL=https://api.example.com

ポイント

• envSchema.parse(...) は失敗時に ZodError を throw するため、未設定・型不一致が起動時に即発覚する
• process.env の参照を src/lib/env.ts 一か所に集約することで、使う側は env.VARIABLE_NAME と書くだけで型安全になる
• NEXT_PUBLIC_ なし変数はサーバーサイドのみ参照可能。クライアントで使うには NEXT_PUBLIC_ を付ける
• z.string().url() / z.string().min(1) などで形式チェックも同時に行える
• .env.local は .gitignore に含まれていることを確認する（シークレットをコミットしない）