Qué son las variables de entorno

Toda aplicación necesita valores que cambian según dónde se ejecute: la dirección de la base de datos, el puerto, el token de un bot, la clave de una API de pagos. Escribirlos directamente en el código funciona en tu computadora y se vuelve un problema en el primer deploy.

Las variables de entorno lo resuelven. El código le pregunta al sistema "¿cuál es el valor de DATABASE_URL?" y cada entorno responde con el suyo. El código es el mismo, la configuración cambia. Es uno de los primeros conceptos que conviene dominar antes de cualquier deploy.

¿Qué es una variable de entorno?#

Es un par nombre-valor que pertenece al entorno de un proceso. Cuando el sistema operativo inicia un programa, le entrega una copia de ese conjunto. El programa puede leerla en cualquier momento, y los procesos hijos que inicie heredan la misma copia.

Ya usas algunas sin notarlo: PATH indica dónde buscar ejecutables y HOME apunta a la carpeta del usuario. Las tuyas son del mismo tipo. En Linux/macOS, el primer ejemplo define la variable solo para ese comando; en PowerShell, el segundo la mantiene hasta que cierres la terminal:

PORT=3000 node index.js

$env:PORT = "3000"; node index.js

Dos reglas valen para todos los lenguajes. Primero, todo valor es texto: 3000 llega como "3000" y false llega como "false" (que en muchos lenguajes es verdadero). Segundo, por convención el nombre no empieza con un dígito y se escribe en MAYÚSCULAS con guion bajo, como API_KEY.

¿Cómo se leen las variables en el código?#

En Node.js están en process.env. En Python, en os.environ, que lanza KeyError si la clave no existe; os.getenv devuelve un valor por defecto en ese caso.

// Node.js
const port = Number(process.env.PORT ?? 3000);
const token = process.env.DISCORD_TOKEN;
if (!token) {
  throw new Error("Define DISCORD_TOKEN antes de iniciar");
}

import os

port = int(os.getenv("PORT", "8000"))
token = os.environ["DISCORD_TOKEN"]  # KeyError si no existe

Usa un valor por defecto para lo opcional (el puerto) y falla pronto para lo obligatorio (el token). Un error claro al iniciar cuesta menos que un undefined que aparece en producción horas después.

¿Por qué no poner la configuración en el código?#

La guía Twelve-Factor App, una referencia clásica para apps en la nube, define la configuración como todo lo que varía entre deploys: credenciales, direcciones de servicios, nombres de host. Su prueba es simple: si pudieras liberar el código ahora mismo sin exponer ninguna credencial, la configuración está bien separada.

Hay tres ventajas prácticas:

• Seguridad. Un token en el código va a Git, y el historial lo guarda para siempre. El token de un bot de Discord o una clave de API subida a un repositorio público queda visible para cualquiera: trátala como comprometida.
• Un código, varios entornos. El mismo build corre en desarrollo, pruebas y producción, cambiando solo las variables.
• Cambios sin tocar el código. Rotar una contraseña es cambiar un valor y reiniciar, sin un nuevo commit.

¿Qué es el archivo .env y cómo se usa?#

Escribir diez variables a mano en cada ejecución cansa. Un archivo .env guarda un NOMBRE=valor por línea y se usa solo en desarrollo:

DISCORD_TOKEN=pega_el_token_aqui
DATABASE_URL=postgres://usuario:clave@localhost:5432/app
PORT=3000

Node.js lee este formato sin librerías con la opción --env-file:

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

Si la variable ya existe en el entorno, gana sobre el valor del archivo. En Python, el paquete python-dotenv hace lo mismo con load_dotenv().

El punto crítico: agrega .env al .gitignore. Para quien clone el proyecto, sube al repositorio un .env.example con los nombres y valores falsos: así todos saben qué configurar.

¿Cómo manejar los secretos?#

Las variables de entorno son mejores que escribir los valores en el código, pero no son una bóveda. Algunas precauciones:

1. No imprimas valores en logs ni en mensajes de error.
2. Da a cada servicio solo las credenciales que necesita.
3. Si un token se filtra, revócalo y genera otro. Borrar el commit no basta, porque el valor pudo haberse copiado ya.
4. Nunca pongas secretos en variables que lee el navegador. En frameworks de front-end, prefijos como NEXT_PUBLIC_ o VITE_ exponen el valor en el JavaScript que recibe el visitante: úsalos solo para datos públicos.

¿Cuándo las variables de entorno no son la mejor opción?#

Para configuración larga y estructurada, como listas de reglas o textos, un archivo de configuración versionado es más legible. Para secretos que rotan todo el tiempo o requieren auditoría de acceso, una bóveda de secretos dedicada tiene más sentido. Para la gran mayoría de bots y APIs, en cambio, las variables de entorno bastan.

Cómo hacerlo en Square Cloud#

En Square Cloud, el .env que usas en desarrollo se convierte en la configuración de producción sin copiar valor por valor: el panel importa el archivo y crea las variables de la aplicación, y exporta todo de vuelta en formato KEY=VALUE cuando lo necesites. También puedes definir cada variable con la CLI (app env set KEY=VALUE), por la API o desde la extensión de VS Code.

Dos detalles siguen las reglas de esta guía. Cada aplicación tiene su propio conjunto de variables y no puede leer las de otra, aunque estén en la misma cuenta, así que tu bot nunca ve las credenciales de tu API. Y un cambio surte efecto en el próximo reinicio, sin volver a subir el código: rotar una contraseña es cambiar el valor y reiniciar. Las variables ya existen mientras se instalan las dependencias, y SQUARECLOUD_APP_ID entrega el ID de la propia aplicación en tiempo de ejecución.

Mira el paso a paso en la página de variables de entorno y los comandos de la CLI.