Sintaxis de los archivos .env: comillas, comentarios, valores multilínea y referencias

Un archivo .env parece simple: un CLAVE=valor por línea. En la práctica, los distintos analizadores no coinciden en los casos límite, lo que causa el error clásico de un valor que funciona en local y falla en producción. Conocer las reglas comunes te ayuda a escribir archivos que se comporten igual en todas partes.

Lo básico

Cada línea contiene una clave, un signo igual y un valor. Las claves suelen ir en mayúsculas con guiones bajos. Las líneas en blanco se ignoran y las que empiezan con # son comentarios.

# Base de datos
DB_HOST=localhost
DB_PORT=5432

Comillas

• Los valores sin comillas terminan al final de la línea y se recortan los espacios de los extremos.
• Las comillas dobles permiten secuencias de escape como \n para un salto de línea y conservan espacios iniciales o finales: DB_NAME="mi app".
• Las comillas simples conservan todo de forma literal, así que 'raw $value' queda exactamente como se escribió.

Si un valor contiene espacios, # o caracteres especiales, ponlo entre comillas.

Comentarios en línea

En la mayoría de los analizadores, un espacio seguido de # inicia un comentario fuera de comillas, así que DEBUG=true # solo local da true. Un # dentro de comillas es parte del valor. Por eso una contraseña con # debe ir entre comillas.

El prefijo export

Algunos archivos escriben export CLAVE=valor para poder cargarlos también desde un shell con source. Muchos analizadores aceptan e ignoran la palabra export.

Valores multilínea

Un valor entre comillas dobles puede ocupar varias líneas, que es como se guardan las claves privadas y los certificados. También puedes escribir \n dentro de las comillas.

Referencias a variables

Algunas herramientas expanden ${HOST} dentro de otros valores, por ejemplo API_URL=https://${DB_HOST}:8080/api. No todos los analizadores lo hacen, así que revisa el tuyo. El conversor resuelve las referencias a variables definidas antes o después en el mismo archivo.

Tipos

Un archivo .env solo contiene cadenas. Al convertir a JSON, 5432 puede pasar a número y true a booleano, lo cual es cómodo, pero recuerda que tu aplicación quizá deba hacer esa misma conversión por su cuenta.

Preguntas frecuentes

¿Por qué mi valor se corta en un espacio? No estaba entre comillas, o un # inició un comentario.