¿Qué son las Variables de Entorno y Cómo Usar Archivos .env?
Domina la gestión de variables de entorno: el archivo `.env`, cómo leerlas en Node.js/Python, qué debe contener el archivo `.env.example` y cómo inyectarlas de forma segura en contenedores y servidores de producción.
Una variable de entorno es un par clave-valor dinámico administrado por el sistema operativo o el runtime que define parámetros de configuración, secretos y credenciales accesibles por los procesos en ejecución sin necesidad de escribirlos de forma fija en el código fuente de la aplicación.
Cumple con el tercer principio de la metodología universal 'The Twelve-Factor App': desacopla la configuración del código, permitiendo que la misma base de código se ejecute de forma transparente en desarrollo, staging y producción simplemente cambiando las variables de entorno, y evitando fugas catastróficas de contraseñas.
Imagina los electrodomésticos de una cocina: una tostadora universal no tiene una etiqueta grabada en metal que diga 'Exclusiva para la cocina de la casa de Pedro'. Tiene un cable con enchufe estándar; si la conectas en tu casa, toma la corriente de tu enchufe (entorno de desarrollo); si la llevas a un restaurante, toma la corriente del restaurante (entorno de producción). Las variables de entorno son ese enchufe que adapta el comportamiento del programa al lugar donde está conectado.
Explicación Paso a Paso del Tema
Crear el archivo .env local y agregarlo a .gitignore
Asegura que tu archivo de secretos jamás se comparta en repositorios de Git.
En la raíz de tu proyecto, crea un archivo llamado `.env`. En él defines tus variables en formato `CLAVE=VALOR`. Acto seguido, abre tu `.gitignore` y escribe `.env` y `.env*.local`. Esto garantiza que tus contraseñas locales nunca se suban a GitHub por accidente.
echo "DATABASE_URL=postgres://admin:pass@localhost:5432/miapp JWT_SECRET=super_secreto_local" > .env echo ".env .env.local" >> .gitignore
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| .env | Archivo de entorno | Almacena los valores concretos utilizados en tu máquina local de desarrollo |
| .gitignore | Exclusión obligatoria | Impide que el archivo de credenciales viaje a la nube o al control de versiones |
Para compartir claves con compañeros de equipo de forma segura, usa gestores de contraseñas de equipo o herramientas como 1Password, Bitwarden o Doppler.
Subir el archivo `.env` al repositorio de GitHub 'solo por esta vez' para que tu compañero lo descargue; bots rastreadores robarán las claves en segundos.
Cargar y leer variables en el código con dotenv
Lee las variables del archivo .env al inicio de la ejecución de tu aplicación.
En Node.js, utiliza el paquete estándar `dotenv` (o el flag nativo moderno `node --env-file=.env app.js`). En Python utilizas `python-dotenv`. Al arrancar el programa, las variables se cargan en la memoria del proceso y puedes acceder a ellas mediante `process.env.NOMBRE_VARIABLE`.
require('dotenv').config();
const puerto = process.env.PORT || 3000;
console.log(`Servidor configurado en puerto: ${puerto}`);| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| dotenv.config() | Inicializador | Lee el archivo .env de la raíz y coloca cada par clave-valor en process.env |
| process.env.PORT || 3000 | Valor de respaldo (Fallback) | Usa la variable de entorno si existe; si no fue definida, usa un valor predeterminado seguro |
En Node.js 20.6 en adelante, ya no necesitas instalar la librería `dotenv`: puedes ejecutar `node --env-file=.env index.js` de forma nativa.
Invocar `process.env.MI_VARIABLE` en un archivo antes de que `dotenv.config()` haya sido ejecutado en el punto de entrada, recibiendo `undefined`.
Documentar con un archivo .env.example
Crea una guía limpia para que cualquier compañero sepa qué variables debe configurar.
Crea un archivo llamado `.env.example` y este SÍ súbelo a Git. En él colocas los nombres exactos de todas las variables que tu aplicación necesita, pero con valores ficticios, comentando qué significa cada una.
# .env.example (SÍ se sube a Git): PORT=3000 DATABASE_URL=postgres://usuario:password@localhost:5432/nombre_db JWT_SECRET=escribe_aqui_una_clave_aleatoria_larga
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| .env.example | Contrato de configuración | Documenta la lista completa de variables necesarias para que el proyecto arranque |
Utiliza librerías de validación como Zod o Envalid para validar las variables de entorno al iniciar la app; si falta una variable crítica, el programa se detendrá de inmediato con un mensaje claro en lugar de fallar a mitad de una transacción.
Añadir una variable nueva en tu `.env` local y olvidar agregarla a `.env.example`; tus compañeros se quedarán con la app rota sin saber qué variable falta.
Casos Prácticos Reales en Producción
Situaciones de ingeniería reales sin mención de presupuestos ficticios.
1Caso de Producción: Filtración de Base de Datos Evitada gracias a Desacoplamiento de Entornos
Un desarrollador realizaba pruebas en su computadora local. Si la conexión a la base de datos hubiera estado 'quemada' en el código apuntando a la base de producción, una prueba de borrado local habría destruido datos de clientes reales.
Gracias al uso estricto de variables de entorno, en su archivo `.env` local la variable `DATABASE_URL` apuntaba a un contenedor local de Docker (`localhost:5432`), mientras que en el servidor de producción la variable apuntaba al clúster de producción inyectada por el panel de la nube.
Fichas Nemotécnicas de Conceptos Clave
Glosario rápido para recordar los términos fundamentales de la lección.
El grave antipatrón de escribir contraseñas, URLs o secretos directamente en las líneas del código fuente.
Objeto global en Node.js que contiene todas las variables de entorno disponibles para el proceso en ejecución.
Archivo plantilla público subido a Git que documenta qué variables necesita el proyecto pero sin incluir valores reales sensibles.
¿Qué son las Variables de Entorno y Cómo Usar Archivos .env?
Selecciona una opción para autoevaluarte al instante. La respuesta se califica de inmediato.
¿Cuál es el propósito primordial de utilizar variables de entorno y archivos .env?
¿Qué archivo debe incluirse OBLIGATORIAMENTE dentro de .gitignore para no exponer credenciales en GitHub?
¿Cuál es la función del archivo '.env.example' que sí se debe compartir en el repositorio?
Preguntas Frecuentes (FAQ)
¿Se debe usar un archivo .env en servidores de producción?
Generalmente no se recomienda tener archivos .env físicos en servidores de producción. En producción, las variables se inyectan directamente en el sistema operativo del servidor, a través del panel del proveedor cloud (AWS ECS, Vercel, Heroku) o mediante Kubernetes Secrets.
¿Por qué las variables de entorno en Frontend en React o Next.js requieren un prefijo especial?
Porque el código Frontend se ejecuta en el navegador del cliente. Por seguridad estricta, frameworks como Next.js solo exponen al navegador aquellas variables que comiencen explícitamente con `NEXT_PUBLIC_` (ej. `NEXT_PUBLIC_ANALYTICS_ID`). Todas las demás se mantienen ocultas en el servidor.
¿Qué ocurre si una variable de entorno contiene espacios o caracteres raros?
Debes envolver el valor entre comillas dobles en tu archivo `.env`: `SALUDO="Hola Mundo con espacios"`.