process.env en Node.js: variables de entorno

process.env es un objeto con una propiedad por cada variable de entorno que la shell pasó a tu programa de Node.js: process.env.PORT, process.env.DATABASE_URL, etc. Una variable que no se definió se lee como undefined, y una que sí se definió es siempre un string. Léela una vez al arrancar, dale un valor por defecto y conviértela al tipo que necesites.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

Imprimió shop on port 8080 in eu-west (REGION nunca se definió, así que se usó su valor por defecto), y luego string number: la variable es texto hasta que Number() la convierte. Borra las dos primeras asignaciones y vuelve a ejecutar para ver todos los valores por defecto.

Definir variables de entorno en la shell

Las variables vienen de donde se lance Node.js. En una terminal:

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

Las plataformas de hosting (Heroku, Render, Vercel, Docker, Kubernetes) tienen una página de configuración o un archivo para lo mismo; tu código las lee igual.

Todo es un string

De aquí salen la mayoría de los bugs con process.env. 'false' y '0' son strings no vacíos, así que son truthy:

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

La comprobación ingenua imprimió debug is ON para una variable con el valor false, así que compara con el string exacto que esperas. Con números, Number(process.env.X) convierte un valor que falta en NaN, así que aplica el valor por defecto antes de convertir, como hizo el primer ejemplo con ??.

NODE_ENV

NODE_ENV es una convención, no una funcionalidad de Node.js: Node.js nunca la define. La leen las librerías. Express, por ejemplo, oculta las stack traces en las páginas de error cuando vale production, y muchas herramientas se saltan comprobaciones solo de desarrollo.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

Imprimió mode: production y verbose logs: false; cambia 'production' por 'development' y la segunda línea se invierte. Quédate con production, development y test, porque las librerías comprueban exactamente esas palabras.

Archivos .env: --env-file y dotenv

Escribir cada variable antes de node acaba cansando. Un archivo .env las guarda en la carpeta del proyecto, una por línea:

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

Node.js 20.6 y posteriores lo leen con un flag, sin paquetes:

node --env-file=.env app.js

En versiones anteriores, o si lo prefieres, instala el paquete dotenv (npm install dotenv) y cárgalo al principio de todo de tu archivo de entrada, antes de que ningún código lea process.env:

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

Ninguno de los dos sobrescribe una variable que ya esté definida en la shell, así que la configuración de producción gana al archivo.

Falla pronto si faltan variables

Si falta la URL de la base de datos, el programa debería pararse al arrancar con un mensaje claro, no romperse con la primera petición una hora después:

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter((key) => !process.env[key]);

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

Imprimió Missing environment variables: API_KEY; añade process.env.API_KEY = 'test'; al principio e imprime Config OK. En un programa real, sigue el mensaje con process.exit(1), porque un código de salida distinto de cero es lo que le indica a un script de despliegue o a una plataforma de contenedores que el arranque falló.

Nunca subas secretos al repositorio

Añade .env a .gitignore el mismo día que lo creas. Sube en su lugar un .env.example con los nombres de las variables y valores falsos, para que los demás sepan qué definir. Una clave que alguna vez se subió a un repositorio debe tratarse como filtrada y reemplazarse, aunque borres el commit después.