Definición
Las variables de entorno son valores de configuración que la aplicación lee del sistema donde se ejecuta, en lugar de tenerlos escritos en el código.
Sirven para todo lo que cambia entre entornos o que no debe estar en el repositorio: la contraseña de la base de datos, la clave de una API, la dirección del servidor de correo, si el modo de depuración está activo.
La regla que las justifica es sencilla: el código es público dentro de tu equipo y viaja a todas partes; los secretos no. El mismo código tiene que poder desplegarse en pruebas y en producción cambiando solo lo de fuera.
Cómo se usan
En desarrollo, lo habitual es un fichero .env en la raíz del proyecto:
DB_HOST=localhost
DB_PASS=una_clave_larga
STRIPE_KEY=sk_test_xxxxx
Y ese fichero va siempre en el .gitignore. Junto a él se deja un .env.example con los nombres de las variables y sin valores, para que cualquiera sepa qué hace falta configurar.
En producción no se sube un .env: los valores se ponen en el panel del hosting, en la configuración del servicio o en un gestor de secretos.
Ejemplo práctico
En mis proyectos hay tres niveles de protección de secretos, según lo que proteja cada uno.
Nivel básico: fichero de configuración fuera del repositorio. El panel de AEWorks tiene un config.local.php que no está en el control de versiones y que lleva el hash de la contraseña de acceso. Sin ese fichero, la aplicación no arranca.
Nivel medio: fuera de la carpeta pública. La base de datos del panel no vive dentro de la web, sino en una carpeta hermana. Aunque alguien acierte la dirección, el servidor devuelve un 404 porque el fichero literalmente no está donde el navegador puede buscarlo.
Nivel alto: cifrado. Las credenciales que los clientes guardan en el panel —accesos a sus hostings, sus dominios— están cifradas con AES-256-GCM. La clave de cifrado es un fichero binario con permisos 0600, fuera de la carpeta pública. Si alguien se lleva la base de datos, se lleva ruido.
Y una cosa que corregí porque no era cierta: en la pantalla de ajustes ponía que la clave de la API de IA se guardaba "cifrada". No lo estaba: era un fichero PHP en el servidor. Cambié el texto para que dijera la verdad y avisara de que quien tenga acceso al servidor puede leerla. Un mensaje de seguridad falso es peor que no poner ninguno, porque te hace bajar la guardia.
Si un secreto acaba en el repositorio
Pasa, y hay que reaccionar bien. Borrarlo en un commit posterior no sirve: el valor sigue en el historial y cualquiera con acceso puede recuperarlo.
El procedimiento correcto es este, y en este orden:
- Rota la credencial inmediatamente. Genera una nueva y desactiva la antigua. Esto es lo urgente.
- Limpia el historial si el repositorio es privado y controlas quién lo ha clonado.
- Si era público, da por comprometida la clave sin más discusión. Hay robots que rastrean repositorios buscando exactamente eso, y tardan minutos.
Errores comunes
- Credenciales escritas en el código. El error de base, y sigue siendo el más común.
- Subir el
.env. Añádelo al.gitignoreen el primer commit, antes de que exista. - Meter secretos en variables que llegan al navegador. En un proyecto de frontend, las variables con cierto prefijo se incrustan en el paquete que se descarga. Cualquiera las lee. Ahí solo van valores públicos.
- Poner secretos en una imagen de Docker. Quedan dentro y viajan con ella.
- Usar las mismas claves en pruebas y en producción. Un script de prueba con la clave real de pagos puede cobrar de verdad.
- No documentar qué variables hacen falta. Sin un fichero de ejemplo, montar el proyecto en otra máquina es adivinar.
- Secretos en los registros. Si vuelcas la configuración en un log de error, ahí se queda en claro.
Cuándo usarlas
Siempre, para cualquier valor que cumpla una de estas tres: es secreto, cambia entre entornos, o es una dirección de un servicio externo.
La prueba rápida para saber si algo debería ser variable de entorno: ¿podría publicar este fichero en internet sin que pasara nada? Si la respuesta es no, ese valor no va en el código.
