Variables de entorno y secretos: cómo gestionar la configuración de tus proyectos

Alguna vez has visto una contraseña de base de datos escrita directamente en el código. Quizás incluso en el tuyo propio, al principio. No pasa nada, todos hemos pasado por ahí.

Pero hay una forma mucho mejor de manejar esto, y no es solo por seguridad. Las variables de entorno hacen que tu código sea más flexible, más portable y más fácil de mantener.

---

Qué es una variable de entorno

Una variable de entorno es un valor de configuración que existe fuera del código, en el entorno donde se ejecuta la aplicación. El sistema operativo, el servidor o el proceso que arranca tu app se las inyecta al proceso en tiempo de ejecución.

En lugar de esto:

$db = new PDO('mysql:host=localhost;dbname=miapp', 'root', 'mi_contraseña_secreta');

Haces esto:

$db = new PDO(
    'mysql:host=' . $_ENV['DB_HOST'] . ';dbname=' . $_ENV['DB_NAME'],
    $_ENV['DB_USER'],
    $_ENV['DB_PASS']
);

El código no sabe cuál es la contraseña. Solo sabe dónde buscarla. Eso es lo importante.

---

Por qué importa más allá de la seguridad

La seguridad es la razón más obvia, pero no la única:

Portabilidad. El mismo código funciona en local, en staging y en producción sin modificar nada. Solo cambian los valores de las variables.

Colaboración. Cada desarrollador puede tener su configuración local sin pisar la de los demás ni la de producción.

Sin secretos en Git. Los repositorios son potencialmente públicos, incluso los privados pueden filtrarse. Los secretos no deben estar en el historial de commits nunca.

Separación de responsabilidades. La configuración es responsabilidad del entorno, no del código.

---

El archivo .env

La forma más común de trabajar con variables de entorno en desarrollo local es el archivo .env. Es un archivo de texto plano con pares clave-valor:

# .env
APP_NAME=MiAplicacion
APP_ENV=local
APP_DEBUG=true

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=miapp
DB_USER=root
DB_PASS=supersecreta

MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USER=usuario
MAIL_PASS=contraseña

Librerías como phpdotenv (PHP), dotenv (Node.js) o los frameworks modernos lo cargan automáticamente al arrancar la aplicación.

---

La regla más importante: .env nunca en Git

Añade .env a tu .gitignore desde el primer commit. Sin excepciones.

# .gitignore
.env
.env.local
.env.production

Lo que sí debe estar en Git es un .env.example con las mismas claves pero sin los valores reales. Sirve como documentación para cualquiera que clone el proyecto:

# .env.example  ← este SÍ va en Git
APP_NAME=
APP_ENV=local
APP_DEBUG=true

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=
DB_USER=
DB_PASS=

---

Cómo acceder a las variables

En PHP:

// Con phpdotenv instalado y cargado
$host = $_ENV['DB_HOST'];
$host = getenv('DB_HOST'); // alternativa

En JavaScript (Node.js):

// Con el paquete dotenv
const host = process.env.DB_HOST;

En la terminal:

export DB_HOST=localhost
echo $DB_HOST

---

Niveles de entorno

Un proyecto suele tener varios entornos con configuraciones distintas:

Entorno	Propósito
local	Tu máquina de desarrollo
testing	Pruebas automatizadas
staging	Preproducción, copia de producción
production	El entorno real con usuarios

Cada entorno tiene su propio conjunto de variables. La base de datos de producción nunca debe ser la misma que la de desarrollo.

---

Secretos en producción: más allá del .env

En producción, copiar un archivo .env al servidor es una opción, pero no la más robusta. Las alternativas más seguras:

Variables del sistema operativo. El servidor tiene las variables configuradas directamente en su entorno. No hay archivo que pueda filtrarse.

Gestores de secretos. Servicios como AWS Secrets Manager, HashiCorp Vault o Doppler almacenan los secretos cifrados y los inyectan en tiempo de ejecución. Tu aplicación ni siquiera ve el valor en texto plano hasta que lo necesita.

Secrets de la plataforma. Servicios como Vercel, Railway o Heroku tienen paneles para definir variables de entorno sin necesidad de archivos.

---

Errores comunes

Subir el .env a Git. El más frecuente. Si ya ocurrió, no basta con borrar el archivo: el secreto está en el historial. Hay que rotar las credenciales (cambiar las contraseñas) y usar git filter-repo para limpiar el historial.

Variables con nombres genéricos. PASSWORD o KEY no dicen nada. Usa nombres descriptivos: DB_PASS, STRIPE_SECRET_KEY, SMTP_PASSWORD.

El mismo .env para todos los entornos. Cada entorno debe tener sus propios valores. Compartir la base de datos de producción con el entorno de desarrollo es una receta para el desastre.

Valores por defecto inseguros en código. Esto es especialmente peligroso:

// MAL: si la variable no existe, usa una contraseña por defecto
$pass = $_ENV['DB_PASS'] ?? 'admin123';

Si una variable crítica no existe, la aplicación debe fallar con un error claro, no continuar con un valor inseguro.

---

Conclusión

Las variables de entorno son una de esas cosas que parecen un detalle técnico menor pero tienen un impacto enorme en la seguridad y en la calidad del proyecto.

La regla es simple: nada que cambie entre entornos, y nada que sea secreto, debe estar en el código.

Si lo aplicas desde el principio de cada proyecto, te ahorrarás más de un problema en el futuro.