dotenv vs Inyección de Plataforma

dotenv carga pares clave-valor de un archivo .env en process.env en tu portátil. Las plataformas de producción inyectan variables de entorno en tiempo de ejecución desde Secrets de k8s, AWS SSM, Vault o paneles de PaaS. La ruta del código Node.js es la misma; solo cambia la fuente.

Receta

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

// src/load-env.ts
import { config as dotenvConfig } from "dotenv";
 
export function bootstrapEnv() {
  if (process.env.NODE_ENV === "test") return;
  if (process.env.NODE_ENV === "production") return; // la plataforma inyecta el entorno
  dotenvConfig(); // solo desarrollo
}

# Dockerfile - NO COPIAR .env
ENV NODE_ENV=production
# DATABASE_URL configurado por k8s/ECS en tiempo de ejecución
CMD ["node", "dist/main.js"]

Cuándo usarlo:

• Incorporación de desarrolladores que necesitan URLs de Postgres locales sin compartir credenciales de producción
• Auditoría de imágenes Docker para detectar la inclusión accidental de secretos
• Diseño de pipelines de CI que reflejan la inyección en producción
• Migración de .env en el repositorio a producción respaldada por un almacén de secretos

Ejemplo de Funcionamiento

// src/load-env.ts
import { config as dotenvConfig } from "dotenv";
import { existsSync } from "node:fs";
 
export function bootstrapEnv(): void {
  const nodeEnv = process.env.NODE_ENV ?? "development";
 
  if (nodeEnv === "production") {
    // La definición de tarea de ECS, el manifiesto de k8s o los secretos de Fly configuran esto
    return;
  }
 
  if (nodeEnv === "test") {
    // El archivo de configuración de Jest/Vitest establece process.env directamente
    return;
  }
 
  const path = existsSync(".env.local") ? ".env.local" : ".env";
  const result = dotenvConfig({ path });
  if (result.error && !existsSync(".env.example")) {
    console.warn(`No se encontró ${path}; copia .env.example a .env`);
  }
}
 
// src/main.ts
import { bootstrapEnv } from "./load-env";
bootstrapEnv();
import { env } from "./env"; // Parseo Zod después del bootstrap
import express from "express";
 
const app = express();
app.listen(env.PORT);

# fragmento de despliegue de kubernetes
env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: api-secrets
        key: database-url
  - name: NODE_ENV
    value: production

Lo que esto demuestra:

• dotenv se ejecuta solo en desarrollo; producción confía en el orquestador
• La imagen Docker no contiene ningún archivo .env
• El mismo esquema Zod de env.ts valida tanto las fuentes locales como las de producción

Análisis Detallado

Cómo Funciona

• dotenv lee .env y asigna a process.env sin sobrescribir las claves existentes (por defecto)
• Las plataformas configuran el entorno antes de que node se inicie; el punto de entrada del contenedor ve process.env completo
• Precedencia: entorno de plataforma > exportación de shell > archivo dotenv (cuando override: false)
• Los gestores de secretos a menudo obtienen al inicio y configuran process.env programáticamente antes del parseo de Zod

Matriz de Entornos

Docker y Compose

# docker-compose.yml - solo desarrollo
services:
  api:
    env_file:
      - .env
    environment:
      NODE_ENV: development

• env_file en Compose es una ergonomía de desarrollo, no un patrón de producción
• Compose de producción (si se usa) debe usar secretos de Docker o un almacén de secretos externo

Notas de TypeScript

// Guardia explícita en el esquema para configuraciones erróneas de producción
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  DATABASE_URL: z.string().url(),
}).refine(
  (e) => e.NODE_ENV !== "production" || !e.DATABASE_URL.includes("localhost"),
  { message: "La DATABASE_URL de producción no puede apuntar a localhost" }
);

Errores Comunes

• Subir .env a git - Fuga instantánea de credenciales. Solución: .gitignore .env; sube .env.example solo con marcadores de posición.
• COPY .env en Dockerfile - Secretos en las capas de la imagen para siempre. Solución: Solo inyección en tiempo de ejecución; escanea imágenes con docker history.
• dotenv en dependencias de producción - Fomenta el mal uso en producción. Solución: devDependencies cuando solo el desarrollo local carga archivos.
• Asumir que dotenv sobrescribe la plataforma - override: true puede sobrescribir los secretos de k8s en configuraciones híbridas. Solución: Mantén el valor predeterminado override: false; omite dotenv por completo en producción.
• Diferentes claves por entorno sin esquema - Staging sin STRIPE_KEY falla en el momento del pago. Solución: Un esquema Zod; CI valida la plantilla de manifiesto de cada entorno.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de configuración - configuración de doce factores
• Zod y validación de esquema de entorno - validar después de la inyección
• Gestores de secretos - patrones de obtención de almacenes de secretos
• Conceptos básicos de Docker - convenciones de entorno de imagen
• Mejores prácticas de configuración - política de equipo

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.