Variables de Entorno y Gestión de Configuración para Aplicaciones Web

Incluir credenciales de bases de datos, tokens de API o flags de funciones directamente en tu código fuente es uno de los riesgos de seguridad más comunes y críticos en el desarrollo web. El uso de variables de entorno permite desacoplar la configuración de la lógica de programación, permitiéndote desplegar el mismo código en entornos de desarrollo, pruebas o producción ajustando únicamente los parámetros necesarios.

La Metodología de la Aplicación de 12 Factores

El estándar de 12-Factor App, definido por expertos de Heroku, establece como regla de oro que la configuración debe residir en el entorno y nunca dentro del repositorio de código. Esto conlleva ventajas esenciales:

• Las URLs de bases de datos y claves privadas jamás deben ser versionadas en Git.
• El código fuente es idéntico en todos los entornos; solo cambian las variables externas.
• La configuración se inyecta dinámicamente en el tiempo de ejecución.

Implementación con archivos .env

# Base de Datos
DATABASE_URL=postgres://usuario:contrasena@localhost:5432/db_desarrollo
DATABASE_POOL_SIZE=10

# Credenciales API
STRIPE_SECRET_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xxxxx

# Configuración General
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

# Flags de Funcionalidad
ENABLE_NEW_CHECKOUT=true
ENABLE_DARK_MODE=false

Cómo leer variables de entorno

// Cargar variables en desarrollo
import 'dotenv/config';

// Acceso a variables
const dbUrl = process.env.DATABASE_URL;
const port = parseInt(process.env.PORT || '3000', 10);
const isDev = process.env.NODE_ENV === 'development';

// Validación estricta al iniciar
const requeridas = ['DATABASE_URL', 'STRIPE_SECRET_KEY'];
for (const key of requeridas) {
  if (!process.env[key]) {
    throw new Error(`Variable de entorno obligatoria no encontrada: ${key}`);
  }
}

// Forma nativa
$dbUrl = getenv('DATABASE_URL');
$debug = getenv('APP_DEBUG') === 'true';

// Con la librería vlucas/phpdotenv (Composer)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['DATABASE_URL', 'APP_KEY'])->notEmpty();

// Acceso global
$apiKey = $_ENV['STRIPE_SECRET_KEY'];

Regla de Oro: El archivo .gitignore

# NUNCA incluyas estos archivos
.env
.env.local
.env.production

# SÍ debes incluir un ejemplo sin valores reales
# .env.example

Es recomendable generar un archivo .env.example que sirva como plantilla. Esto documenta las variables requeridas para que el equipo sepa qué configurar sin revelar secretos confidenciales.

DATABASE_URL=postgres://usuario:contrasena@servidor:puerto/base
STRIPE_SECRET_KEY=tu_clave_de_prueba_aqui
NODE_ENV=development
PORT=3000

Configuración por entorno

• Desarrollo: Modo depuración activado, logs detallados, base de datos local y claves de prueba.
• Staging: Modo depuración desactivado, entorno espejo de producción, claves de pre-producción.
• Producción: Depuración deshabilitada, logs mínimos, base de datos real, claves cifradas y HTTPS estricto.

Seguridad en Producción

En servidores de producción, evita el uso de archivos .env estáticos. Implementa soluciones robustas de gestión de secretos:

• Servicios Cloud: AWS Secrets Manager, Google Secret Manager o Azure Key Vault.
• HashiCorp Vault: Gestión centralizada con rotación de credenciales y auditoría detallada.
• Variables CI/CD: Secretos protegidos en GitHub Actions, GitLab CI o configuraciones de entorno en Vercel.
• Contenedores: Docker secrets o inyección directa mediante docker-compose.yml.

Errores comunes a evitar

• Hacer commit del archivo .env: Si ocurre, considera todas esas claves como comprometidas y cámbialas inmediatamente.
• Reutilizar claves de API: Nunca uses los mismos tokens de producción en tu entorno local.
• Omitir validaciones al inicio: Valida que las variables existan apenas inicie la app para evitar fallos inesperados.
• Acceder a process.env disperso: Centraliza el acceso a la configuración en un archivo dedicado (ej: config.js).