Variables de Entorno: Guía para Desarrolladores

Variables de Entorno: Configuración Hecha Bien

Claves de API, URLs de base de datos y feature flags hardcodeadas son la causa #1 de incidentes de seguridad en equipos pequeños. Las variables de entorno resuelven esto separando configuración del código. Tu app lee DATABASE_URL en vez de contener postgres://admin:password123@prod-db:5432.

Por Qué Variables de Entorno

La metodología 12-factor app lo dice mejor: almacena config en el entorno. Beneficios:

• Seguridad: Los secretos no están en tu historial git
• Flexibilidad: El mismo código corre en dev, staging y prod con configs diferentes
• Simplicidad: Sin formatos complejos de archivos de config para parsear

El Archivo .env

La mayoría de los frameworks soportan un archivo .env en la raíz del proyecto:

# .env — NUNCA commitees este archivo
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-here
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_API_URL=https://api.example.com
NODE_ENV=development
PORT=3000

Cárgalo en tu app:

// Node.js — dotenv (más común)
import 'dotenv/config';
// o
require('dotenv').config();

console.log(process.env.DATABASE_URL);
// "postgres://user:pass@localhost:5432/mydb"

# Python — python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()
db_url = os.getenv('DATABASE_URL')

Convenciones de Nomenclatura

Crítico: Solo las variables con el prefijo específico del framework se exponen al browser. Nunca pongas secretos en variables NEXT_PUBLIC_ o VITE_ — estarán en tu bundle JavaScript.

Jerarquía de Archivos de Entorno

La mayoría de los frameworks cargan env files en esta prioridad (posterior sobrescribe anterior):

.env                # Valores por defecto, commiteado al repo (¡sin secretos!)
.env.local          # Overrides locales, gitignored
.env.development    # Específico de desarrollo
.env.production     # Específico de producción
.env.test           # Específico de tests

Secretos en CI/CD

Nunca pongas secretos reales en archivos .env que se despliegan. Usa la gestión de secretos de tu plataforma CI/CD:

# GitHub Actions
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
    steps:
      - run: npm run deploy

# Docker Compose
services:
  app:
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    # O desde un archivo:
    env_file:
      - .env.production

Validación al Inicio

No esperes un crash en runtime para descubrir que falta una env var. Valida al inicio:

// TypeScript con zod
import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(['development', 'production', 'test']),
});

export const env = envSchema.parse(process.env);
// Lanza excepción inmediatamente si alguna variable falta o es inválida

# Python con pydantic
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    jwt_secret: str
    port: int = 3000
    debug: bool = False

    class Config:
        env_file = '.env'

settings = Settings()  # Valida en la instanciación

Errores Comunes

• Commitear .env en git. Agrégalo al .gitignore antes del primer commit. Verifica con git log -- .env.
• Usar env vars para datos estructurados. ALLOWED_ORIGINS=http://localhost:3000,https://myapp.com funciona, pero para config compleja, usa un archivo de config que lea env vars.
• Formatos .env diferentes entre herramientas. Algunas herramientas necesitan comillas, otras no. KEY="value" y KEY=value se comportan diferente en shell vs dotenv.
• Olvidar reiniciar. Las env vars se leen al inicio del proceso. Cambiar el .env requiere reiniciar el servidor.

Gestiona tus env files: Formateador Env — ordena, deduplica y valida tus archivos .env.