Cómo Configurar y Usar Variables de Entorno en Node.js: Guía Práctica

Poner credenciales de base de datos, claves de API y secretos directamente en el código fuente es la forma más rápida de sufrir una brecha de seguridad. Las aplicaciones en producción gestionan estos datos sensibles con variables de entorno: vamos a hacerlo bien desde el principio.

Por Qué Importan las Variables de Entorno

1. Hardcodear todo en el código: contraseña de la base de datos en config.js, clave de API en un comentario, secretos subidos a git. Es la receta perfecta para ser hackeado. No lo hagas.
2. Usar variables de entorno: separas los datos sensibles del código. Puedes tener valores diferentes para desarrollo, staging y producción. Es más seguro, escalable y es el estándar de la industria.
3. Usar un gestor de secretos: AWS Secrets Manager, HashiCorp Vault, etc. Es el enfoque típico en entornos empresariales y arquitecturas grandes.

Qué Son en Realidad las Variables de Entorno

DB_PASSWORD=supersecret123
API_KEY=abc123xyz789
NODE_ENV=production

const password = process.env.DB_PASSWORD; // "supersecret123"
const apiKey = process.env.API_KEY;       // "abc123xyz789"
const env = process.env.NODE_ENV;        // "production"

Por Qué Esto Es Importante

El Problema: Configurarlas a Mano Es Pesado

export DB_HOST=localhost
export DB_PASSWORD=mypassword
export API_KEY=key123

$env:DB_HOST="localhost"
$env:DB_PASSWORD="mypassword"
$env:API_KEY="key123"

Usar Dotenv: el Camino Sencillo

Paso 1: Instalar Dotenv

npm install dotenv

yarn add dotenv

Paso 2: Crear un Archivo .env

DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=mysecurepassword
API_KEY=abc123xyz789
NODE_ENV=development
JWT_SECRET=your-jwt-secret-key
LOG_LEVEL=info

Paso 3: Cargar las Variables en Tu App

// app.js o server.js – PRIMERA LÍNEA
require('dotenv').config();


// Ahora ya puedes usar process.env
const express = require('express');
const app = express();


const dbHost = process.env.DB_HOST;
const dbPort = process.env.DB_PORT;
const apiKey = process.env.API_KEY;


console.log(`Conectando a la base de datos en ${dbHost}:${dbPort}`);
app.listen(3000);

Paso 4: Añadir .env al .gitignore

# .gitignore
.env
.env.local
.env.*.local

Paso 5: Compartir una Plantilla (Sin Secretos)

# .env.example – Este sí se sube al repositorio
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=change_me
API_KEY=change_me
NODE_ENV=development
JWT_SECRET=change_me
LOG_LEVEL=info

cp .env.example .env
# Después edita .env con los valores reales

Ejemplo Práctico: API en Express con Variables de Entorno

// server.js
require('dotenv').config();


const express = require('express');
const postgres = require('pg');


const app = express();


// Leer configuración desde las variables de entorno
const config = {
  db: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME
  },
  api: {
    port: process.env.PORT || 3000,
    apiKey: process.env.API_KEY,
    jwtSecret: process.env.JWT_SECRET
  },
  env: process.env.NODE_ENV || 'development'
};


// Validar variables obligatorias
if (!config.api.apiKey) {
  throw new Error('La variable de entorno API_KEY es obligatoria');
}


// Conectar a la base de datos
const pool = new postgres.Pool(config.db);


// Rutas
app.get('/api/users', (req, res) => {
  const authHeader = req.headers.authorization;
  const token = authHeader?.split(' ');[1]


  // Verificar el token usando JWT_SECRET
  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }


  // Consultar la base de datos usando el pool
  pool.query('SELECT * FROM users', (err, result) => {
    if (err) throw err;
    res.json(result.rows);
  });
});


// Iniciar servidor
const port = config.api.port;
app.listen(port, () => {
  console.log(`Servidor escuchando en el puerto ${port} en modo ${config.env}`);
});

• Las credenciales de la base de datos vienen del .env
• Las claves de API y otros secretos son variables de entorno
• El mismo código funciona en desarrollo, staging y producción cambiando solo el .env
• Nada sensible se guarda en tu repositorio git

Buenas Prácticas para Variables de Entorno

1. Validar Variables Críticas al Arrancar

require('dotenv').config();


const required = ['DB_HOST', 'DB_USER', 'DB_PASSWORD', 'API_KEY'];
const missing = required.filter(key => !process.env[key]);


if (missing.length > 0) {
  throw new Error(`Faltan variables de entorno obligatorias: ${missing.join(', ')}`);
}

2. Centralizar la Configuración en un Objeto

// config.js
require('dotenv').config();


module.exports = {
  database: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD
  },
  api: {
    key: process.env.API_KEY,
    jwtSecret: process.env.JWT_SECRET
  },
  app: {
    port: process.env.PORT || 3000,
    environment: process.env.NODE_ENV || 'development'
  }
};


// Uso
const config = require('./config');
console.log(config.database.host);

3. Usar Distintos .env para Cada Entorno

.env            # Por defecto / desarrollo
.env.production # Config específica de producción
.env.test       # Entorno de tests

const envFile = process.env.NODE_ENV === 'production'
  ? '.env.production'
  : '.env';

require('dotenv').config({ path: envFile });

4. Agrupar Variables con Prefijos

# Base de datos
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin


# Redis
REDIS_HOST=localhost
REDIS_PORT=6379


# Servicios externos
STRIPE_API_KEY=sk_...
SENDGRID_API_KEY=SG_...

5. Documentar Cada Variable

# Conexión a PostgreSQL
DB_HOST=localhost      # Host de la base de datos
DB_PORT=5432           # Puerto de PostgreSQL
DB_USER=admin          # Usuario de la base de datos
DB_PASSWORD=change_me  # Contraseña de la base de datos


# Configuración de APIs
API_KEY=change_me      # Clave de API de un servicio externo
JWT_SECRET=change_me   # Secreto para firmar JWTs


# Aplicación
PORT=3000              # Puerto del servidor Express
NODE_ENV=development   # Entorno (development/staging/production)

Alternativas a Dotenv en Producción

AWS Secrets Manager

HashiCorp Vault

Variables en CI/CD

Kubernetes Secrets

Aprender Node.js de Forma Profesional

En Resumen: Los Secretos No Van en el Código