El archivo .env: para qué sirve y cómo crearlo

Todo proyecto tiene valores que no pertenecen al código: el token de un bot, la contraseña de la base de datos, la clave de una API. Escribir todo eso en la terminal en cada ejecución cansa, y ponerlo en el código es peligroso. El archivo .env es la solución habitual: un archivo de texto junto al proyecto, que se lee al iniciar.

En la práctica, es solo una forma de llenar las variables de entorno en desarrollo. El sistema operativo no lee el archivo: quien lo lee es el runtime (Node.js) o una biblioteca (python-dotenv), que copia los pares al proceso.

¿Cuál es la sintaxis de un archivo .env?#

Una variable por línea, en formato NOMBRE=valor. No existe un estándar oficial único, pero las reglas de abajo valen en Node.js y en python-dotenv:

DEBUG=false # comentario
DISCORD_TOKEN=pega_el_token_aqui
PORT=3000
DATABASE_URL="postgresql://usuario:clave@localhost:5432/mibase" # comentario al final
FRASE='aquí el # no empieza un comentario'
CLAVE_PRIVADA="línea 1
línea 2"
export NODE_ENV=development

• Los nombres usan letras, números y guion bajo, sin empezar con un número, en general en MAYÚSCULAS. En Node.js, my-var y 1_VAR son inválidos.
• Las comillas son opcionales, pero necesarias cuando el valor tiene # o varias líneas. Los valores entre comillas pueden ocupar más de una línea.
• Todo es texto. PORT=3000 llega como "3000" y DEBUG=false llega como "false", que en JavaScript y Python es verdadero. Conviértelo en el código.
• export al principio de la línea se acepta y se ignora, lo que permite cargar el mismo archivo con source .env en el shell.

Cuidado también con $ en los valores. Next.js expande $OTRA_VAR dentro de archivos .env y exige \$ para un signo de dólar literal. python-dotenv solo expande la forma ${VAR}.

¿Cómo cargar el .env en Node.js?#

Las versiones recientes de Node.js tienen soporte nativo, sin instalar ningún paquete, y la flag --env-file ya no es experimental:

node --env-file=.env index.js

// index.js
const token = process.env.DISCORD_TOKEN;
if (!token) throw new Error("DISCORD_TOKEN no está definido");

const port = Number(process.env.PORT ?? 3000);
console.log(`Iniciando en el puerto ${port}`);

Si el archivo no existe, --env-file da error. Usa --env-file-if-exists=.env, que también viene en las versiones recientes de Node.js, cuando el archivo es opcional, por ejemplo en producción. También puedes cargarlo desde el código con process.loadEnvFile('.env'), y util.parseEnv() solo interpreta el texto, sin tocar process.env.

Puedes pasar varios archivos. Los posteriores sobrescriben a los anteriores, pero una variable ya definida en el entorno siempre gana sobre el archivo:

node --env-file=.env --env-file=.env.local index.js

¿Cómo cargar el .env en Python?#

Usa el paquete python-dotenv:

pip install python-dotenv

import os
from dotenv import load_dotenv

load_dotenv()  # busca .env en la carpeta del script o más arriba

token = os.environ["DISCORD_TOKEN"]  # KeyError si falta
port = int(os.getenv("PORT", "3000"))
print(f"Iniciando en el puerto {port}")

Por defecto load_dotenv() no reemplaza variables que ya existen en el entorno; load_dotenv(override=True) hace lo contrario. Si solo quieres leer los valores sin modificar os.environ, usa dotenv_values(".env"), que devuelve un diccionario.

En otros frameworks el archivo puede leerse solo. Next.js carga .env, .env.local y variantes por NODE_ENV, y solo expone al navegador las variables con prefijo NEXT_PUBLIC_, que se graban en el JavaScript en el momento del build. En Docker Compose, la clave env_file del servicio carga las variables del archivo en el entorno del contenedor.

¿Cómo no filtrar los secretos del .env?#

El riesgo real del .env es que termine en el repositorio. Haz esto antes del primer commit:

1. Crea un .gitignore con la línea .env (y .env.* si usas variantes, dejando pasar solo .env.example).
2. Versiona un .env.example con los nombres y valores falsos, para que quien clone el proyecto sepa qué completar:

DISCORD_TOKEN=
DATABASE_URL=postgresql://usuario:clave@localhost:5432/mibase
PORT=3000

3. Confirma con git status que el .env no aparece como archivo nuevo.
4. Nunca imprimas valores en los logs ni los muestres en capturas de pantalla de errores.

Si un secreto ya se subió en un commit, borrar el archivo no lo resuelve, porque el historial guarda el contenido. Genera una clave nueva y revoca la antigua. El paso a paso está en clave de API expuesta en GitHub, y para bots vale la pena ver el token del bot de Discord.

¿Qué errores son comunes con .env?#

La variable llega como undefined. El archivo no se cargó (faltó --env-file o load_dotenv()), está en otra carpeta (la ruta de --env-file es relativa al directorio actual, no al script) o el nombre tiene un error de tipeo.

Cambié el valor y nada cambió. El proceso lee el archivo solo al iniciar: reinícialo. Si la variable también existe en el entorno, esa gana sobre el archivo. Ejecuta echo $DISCORD_TOKEN (o $env:DISCORD_TOKEN en PowerShell) para verlo.

El valor llegó cortado en el #. Pon el valor entre comillas.

PORT no funciona como número. Es texto. Conviértelo con Number() o int().

La variable del front-end aparece vacía. En frameworks como Next.js, solo las variables con prefijo NEXT_PUBLIC_ llegan al navegador, y el valor se fija en el build. Nunca uses ese prefijo para secretos.

Cómo hacerlo en Square Cloud#

En Square Cloud, las variables de entorno se configuran por aplicación, en el panel, por la API, por la CLI o por la extensión de VS Code. El código sigue leyendo process.env u os.environ normalmente.

Si ya tienes un .env listo, el panel importa el archivo y llena las variables. También puedes exportarlo todo de vuelta como KEY=VALUE. El cambio vale en el próximo reinicio de la aplicación, sin rebuild. Dentro de la aplicación, la variable SQUARECLOUD_APP_ID trae su ID en tiempo de ejecución.

Así el .env se queda solo en tu computadora, listado en el .gitignore, y los valores de producción quedan configurados en la propia aplicación. Mira los detalles en variables de entorno en Square Cloud.