Software Development
Coding
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
Estás desarrollando una aplicación en Node.js. Tu código necesita una contraseña de base de datos, una clave de API de un servicio externo y configuración que cambia entre desarrollo y producción.
Tienes básicamente tres opciones:
-
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. -
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.
-
Usar un gestor de secretos: AWS Secrets Manager, HashiCorp Vault, etc. Es el enfoque típico en entornos empresariales y arquitecturas grandes.
Para la mayoría de proyectos con Node.js, sobre todo al principio, variables de entorno junto con dotenv es la mejor solución.
Qué Son en Realidad las Variables de Entorno
Las variables de entorno son valores definidos a nivel del sistema operativo a los que tu aplicación puede acceder en tiempo de ejecución.
Por ejemplo, si defines:
DB_PASSWORD=supersecret123
API_KEY=abc123xyz789
NODE_ENV=production
Tu aplicación puede leer estos valores sin que aparezcan en el código fuente:
const password = process.env.DB_PASSWORD; // "supersecret123"
const apiKey = process.env.API_KEY; // "abc123xyz789"
const env = process.env.NODE_ENV; // "production"
El sistema operativo inyecta estas variables en
process.env, un objeto global que Node.js expone cuando el proceso se inicia.Por Qué Esto Es Importante
Seguridad: Los secretos no aparecen en tu código ni en el historial de git. Aunque tu repositorio sea público, tus credenciales no quedan expuestas.
Gestión de configuración: Distintos entornos (desarrollo, staging, producción) pueden usar valores diferentes sin cambiar ni una línea de código.
Flexibilidad de despliegue: Puedes desplegar el mismo código en servidores distintos. Cada entorno define sus variables de entorno y la aplicación se adapta sola.
El Problema: Configurarlas a Mano Es Pesado
Configurar variables de entorno a mano para cada desarrollador y para cada despliegue es tedioso.
En macOS/Linux:
export DB_HOST=localhost
export DB_PASSWORD=mypassword
export API_KEY=key123
En Windows (PowerShell):
$env:DB_HOST="localhost"
$env:DB_PASSWORD="mypassword"
$env:API_KEY="key123"
Cada persona del equipo tiene que repetir este proceso. Cada pipeline de CI/CD también. Es fácil equivocarse o olvidarse de alguna variable.
Ahí es donde entra
dotenv.Usar Dotenv: el Camino Sencillo
Dotenv es una librería para Node.js que carga automáticamente las variables definidas en un archivo
.env dentro de process.env.Paso 1: Instalar Dotenv
npm install dotenv
o con Yarn:
yarn add dotenv
Paso 2: Crear un Archivo .env
Crea un archivo
.env en la raíz de tu proyecto: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
Al inicio de tu aplicación (antes de cualquier otro código que use estas variables), importa y configura dotenv:
// 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);
Crítico: Llama a
require('dotenv').config() antes de cualquier require que dependa de variables de entorno.Paso 4: Añadir .env al .gitignore
NUNCA hagas commit del archivo
.env al repositorio. Tus secretos quedarían públicos.# .gitignore
.env
.env.local
.env.*.local
Paso 5: Compartir una Plantilla (Sin Secretos)
Crea un archivo
.env.example con las mismas claves pero con valores de ejemplo:# .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
Cada desarrollador copia este archivo y completa los valores reales de forma local:
cp .env.example .env
# Después edita .env con los valores reales
Ejemplo Práctico: API en Express con Variables de Entorno
Veamos un ejemplo realista usando Express.js:
// 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}`);
});
Con esta estructura:
- 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
No esperes a que falle la conexión para descubrir que
DB_PASSWORD no está definida.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
En lugar de usar
process.env.XYZ repartido por todo el código, crea un módulo de configuración central:// 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
Y cargar el archivo correspondiente:
const envFile = process.env.NODE_ENV === 'production'
? '.env.production'
: '.env';
require('dotenv').config({ path: envFile });
4. Agrupar Variables con Prefijos
Usa prefijos para agrupar variables relacionadas y ganar claridad:
# 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
En
.env.example, añade comentarios explicando cada campo:# 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
Para desarrollo y proyectos pequeños, dotenv es ideal. Para aplicaciones grandes y entornos de producción, vale la pena considerar:
AWS Secrets Manager
Guarda los secretos en AWS y recupéralos en tiempo de ejecución. Es más seguro en arquitecturas cloud.
HashiCorp Vault
Gestión de secretos a nivel enterprise, con rotación, auditoría y control de acceso detallado.
Variables en CI/CD
Plataformas como GitHub Actions, GitLab CI o CircleCI permiten definir variables de entorno directamente en el pipeline. No hace falta usar
.env en el servidor.Kubernetes Secrets
Si ejecutas en Kubernetes, puedes usar Secrets y ConfigMaps para manejar configuración y credenciales.
Para aprender y trabajar con Node.js en entornos formativos como Archi's Academy, el patrón recomendado es empezar con dotenv y luego evolucionar hacia gestores de secretos cuando el proyecto lo requiera.
Aprender Node.js de Forma Profesional
Las variables de entorno son solo una pieza de una API Node.js lista para producción. Saber configurar, desplegar y operar tus servicios es lo que diferencia a quien solo “escribe código” de quien realmente pone software en producción.
En Archi's Academy, el Backend Development track te enseña no solo a escribir código en Node.js, sino a configurarlo, desplegarlo y escalarlo en entornos reales.
Learn by Doing. Prove by Doing. Get Hired.
En Resumen: Los Secretos No Van en el Código
Hardcodear secretos en el código es un riesgo de seguridad serio. Las variables de entorno son el estándar de la industria para gestionar configuración sensible. Si dominas este patrón desde el principio, reduces drásticamente el riesgo de exponer credenciales.
Empieza usando dotenv en desarrollo, entiende bien el flujo. A medida que tu aplicación crezca, evoluciona hacia gestores de secretos más avanzados cuando tenga sentido.
¿Tienes dudas sobre variables de entorno, configuración en Node.js o buenas prácticas de backend? El equipo de Archi's Academy está listo para ayudarte: contáctanos cuando quieras.
Monday, Jul 20, 2026