Validación con Zod y env-schema

Zod valida process.env al iniciar Node.js para que las implementaciones mal configuradas fallen antes de aceptar tráfico. Un esquema te proporciona comprobaciones en tiempo de ejecución y tipos de TypeScript sin desviaciones.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import { z } from "zod";
 
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});
 
export type Env = z.infer<typeof envSchema>;
export const env = envSchema.parse(process.env);

# CI: valida el archivo .env de ejemplo
npx tsx -e "import { envSchema } from './src/env'; envSchema.parse(require('dotenv').config({path:'.env.example'}).parsed)"

Cuándo usarlo:

• Cualquier servicio con más de 3 variables de entorno
• Comprobaciones de paridad de entorno de staging/producción en CI
• Prevención de URLs de base de datos undefined en tiempo de ejecución
• Equipos que incorporan nuevos ingenieros que copian .env.example

Ejemplo de trabajo

// src/env.ts
import { z } from "zod";
 
const envSchema = z
  .object({
    NODE_ENV: z.enum(["development", "test", "production"]),
    PORT: z.coerce.number().default(3000),
    DATABASE_URL: z.string().url(),
    REDIS_URL: z.string().url().optional(),
    CACHE_TTL_SECONDS: z.coerce.number().positive().default(300),
    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
  })
  .refine(
    (e) => e.NODE_ENV !== "production" || e.OTEL_EXPORTER_OTLP_ENDPOINT,
    { message: "OTEL_EXPORTER_OTLP_ENDPOINT requerido en producción", path: ["OTEL_EXPORTER_OTLP_ENDPOINT"] }
  );
 
export type Env = z.infer<typeof envSchema>;
 
function formatZodError(error: z.ZodError): string {
  return error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("\n");
}
 
export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
  const result = envSchema.safeParse(source);
  if (!result.success) {
    console.error("Configuración de entorno inválida:\n" + formatZodError(result.error));
    process.exit(1);
  }
  return result.data;
}
 
export const env = loadEnv();
 
// src/main.ts
import { env } from "./env";
import express from "express";
 
const app = express();
app.get("/health", (_req, res) => res.json({ ok: true, env: env.NODE_ENV }));
app.listen(env.PORT);

Lo que esto demuestra:

• safeParse + process.exit(1) proporciona una salida de error amigable para el operador
• z.coerce.number() maneja puertos de cadena del entorno de Kubernetes
• .refine impone requisitos solo para producción
• z.infer exporta Env para tipado de inyección de dependencias

Análisis profundo

Cómo funciona

• Las variables de entorno son siempre cadenas (o indefinidas); Zod las coacciona y valida
• parse lanza ZodError; safeParse devuelve { success, data | error }
• El esquema se ejecuta una vez al cargar el módulo o al llamar explícitamente a loadEnv()
• La configuración inválida nunca llega a los manejadores de rutas o a los pools de DB

Patrones comunes de Zod para el entorno

// Blob de configuración JSON en una variable de entorno (usar con moderación)
const featureFlagsSchema = z
  .string()
  .default("{}")
  .transform((s, ctx) => {
    try {
      return JSON.parse(s) as Record<string, boolean>;
    } catch {
      ctx.addIssue({ code: "custom", message: "FEATURE_FLAGS_JSON debe ser JSON válido" });
      return z.NEVER;
    }
  });

Alternativa env-schema

El paquete env-schema se integra con Fastify y JSON Schema. Zod es más común en bases de código Express/Nest que priorizan TypeScript y se compone con esquemas de cuerpo de solicitud.

Notas de TypeScript

// Pasa Env a las fábricas - nunca pases todo process.env
export function createDbPool(cfg: Pick<Env, "DATABASE_URL">) {
  return new Pool({ connectionString: cfg.DATABASE_URL });
}

Errores comunes

• Analizar el entorno en cada importación de archivo de prueba - El orden importa si env.ts sale por variables faltantes. Solución: loadEnv(testEnv) con un ayudante reset o vi.stubEnv.
• Valores predeterminados que ocultan secretos de producción faltantes - .default("changeme") en JWT_SECRET. Solución: No hay valores predeterminados en los secretos; falla si están ausentes en producción.
• Registrar el entorno analizado - console.log(env) filtra secretos. Solución: Registra solo las claves o usa un serializador redactado.
• Esquemas enormes en un solo archivo - 40 variables se vuelven inmanejables. Solución: Divide por dominio (dbEnv, authEnv) y fusiona con .merge().
• Omitir la validación de .env.example en CI - El archivo de ejemplo se desvía del esquema. Solución: El trabajo de CI analiza .env.example a través del esquema.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de configuración - resumen de doce factores
• dotenv vs Inyección de plataforma - de dónde provienen los valores
• Gestores de secretos - obtención de secretos en tiempo de ejecución
• Mejores prácticas de configuración - estándares del equipo
• Zod - conceptos básicos de la biblioteca

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.