Variables de entorno en PM2: configuración, actualización y buenas prácticas

Las variables de entorno de PM2 son de esas cosas que parecen sencillas hasta que te dan un mordisco. Defines una variable, reinicias el proceso y nada cambia. O usas la opción equivocada y te preguntas por qué tu aplicación está escuchando en el puerto que no es. He visto a desarrolladores con experiencia tropezar con estos errores, y la antigua documentación de PM2 no ayuda mucho.

Esta guía cubre la forma correcta de definir, actualizar y proteger las variables de entorno en PM2 (actualmente en la versión 7.0.3, que requiere Node.js 18+). Si buscas una visión más general de la gestión de procesos, consulta primero cómo gestionar aplicaciones con PM2. Para quienes administran varias aplicaciones en un VPS, los mejores paneles autoalojados de gestión de servidores pueden ayudar a tener visibilidad de todo el stack.

Definir variables de entorno desde la línea de comandos en PM2

La forma correcta de pasar variables de entorno al iniciar un proceso de PM2 usa la sintaxis estándar de variables de entorno de Unix: antepón al comando VAR=valor.

# ❌ Así NO funcionan las variables de entorno de PM2
pm2 start app.js --env PORT=3000
pm2 start app.js --env PORT=3000,DB_URL=mongodb://localhost:27017/mydb

# Una sola variable:
PORT=3000 pm2 start app.js

# Varias variables (separadas por espacios):
PORT=3000 DB_URL=mongodb://localhost:27017/mydb SECRET=abc123 pm2 start app.js

Comprueba que funcionó:

# Primero busca el ID de tu proceso
pm2 list

# Luego inspecciona el entorno (sustituye 0 por el id de tu proceso)
pm2 env 0

Deberías ver PORT=3000 en la salida. Si no aparece, revisa la sintaxis del prefijo. Las variables deben ir antes de pm2 start.

Para el modo clúster de PM2 con varias instancias, normalmente querrás puertos distintos por instancia. increment_var lo gestiona automáticamente (consulta la sección avanzada).

Definir variables de entorno con archivos de ecosistema de PM2

Para cualquier aplicación en producción, el archivo de ecosistema es el enfoque adecuado. Te da un único archivo de configuración que define tu aplicación, sus variables de entorno y cómo debe ejecutarla PM2.

Bloques básicos env, env_production y env_development

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: "my-app",
      script: "./app.js",
      // Entorno por defecto. Se usa cuando no se pasa --env
      env: {
        NODE_ENV: "development",
        PORT: 3000,
        APP_LOG_LEVEL: "debug",
      },
      // Se usa con: pm2 start ecosystem.config.js --env production
      env_production: {
        NODE_ENV: "production",
        PORT: 3000,
        APP_LOG_LEVEL: "info",
      },
      // Se usa con: pm2 start ecosystem.config.js --env staging
      env_staging: {
        NODE_ENV: "staging",
        PORT: 3000,
        APP_LOG_LEVEL: "warn",
      },
    },
  ],
};

Cada bloque env_* corresponde a un nombre que pasas con --env. El bloque base env es el predeterminado cuando no se usa --env.

Cambiar de entorno con –env [nombre]

# Iniciar con el entorno de desarrollo (predeterminado):
pm2 start ecosystem.config.js

# Iniciar con el entorno de producción:
pm2 start ecosystem.config.js --env production

# Iniciar con el entorno de staging:
pm2 start ecosystem.config.js --env staging

Formatos modernos de archivos de ecosistema y generación de plantillas

PM2 admite más que simples archivos .js:

• ecosystem.config.js / ecosystem.config.cjs / ecosystem.config.mjs
• ecosystem.json / ecosystem.json5
• ecosystem.yaml / ecosystem.yml

Para generar una configuración inicial:

pm2 init simple

Esto crea un ecosystem.config.js básico que puedes completar.

Comprueba:

pm2 start ecosystem.config.js --env production
pm2 env 0   # Confirma que aparece NODE_ENV=production

Si aparecen los valores del bloque equivocado, el nombre de --env no coincide con la clave de tu archivo de ecosistema. --env prod no coincidirá con env_production. El nombre debe coincidir exactamente.

Cómo actualizar las variables de entorno de una aplicación PM2 en ejecución

Aquí es donde la mayoría de la gente se atasca. PM2 es conservador por defecto: las variables de entorno son esencialmente inmutables una vez que el proceso arranca.

La opción –update-env

Para cambiar una variable en un proceso iniciado por CLI:

# Define el nuevo valor y reinicia con --update-env
PORT=4000 pm2 restart my-app --update-env

Para confirmar que el cambio surtió efecto:

pm2 env 0   # Busca PORT=4000

Para cambios en el archivo de ecosistema, basta con reiniciar con la misma opción --env:

# Edita env_production en ecosystem.config.js y luego:
pm2 restart ecosystem.config.js --env production

Las variables del archivo de ecosistema siempre se actualizan al reiniciar. No necesitas --update-env para ellas.

Borrado completo + reinicio para variables rebeldes

Algunas variables, sobre todo NODE_ENV, se leen una sola vez al arrancar y no cambian ni con --update-env. Cuando eso ocurre, borrar y volver a crear es la única vía fiable:

pm2 delete my-app
pm2 start ecosystem.config.js --env production

Es un comportamiento conocido. Los informes de la comunidad (issues de GitHub #3192, #4135, #5591) confirman que --update-env puede ser poco fiable en ciertos casos extremos. Ante la duda, borra y vuelve a crear.

La trampa de pm2 save / pm2 resurrect

Si usas pm2 save para persistir tu lista de procesos y reiniciarla automáticamente al arrancar el servidor (vía pm2 startup), ten en cuenta: pm2 save congela las variables de entorno actuales en el archivo de volcado. Cuando luego ejecutas pm2 resurrect, se usan esos valores guardados, aunque hayas modificado el archivo de ecosistema.

La solución: tras cambiar las variables de entorno, borra y vuelve a crear tus procesos, y después guarda de nuevo:

pm2 delete my-app
pm2 start ecosystem.config.js --env production
pm2 save

Funciones avanzadas de variables de entorno en PM2

Estas funciones son especialmente importantes cuando ejecutas varias instancias o despliegas en varios entornos en el mismo servidor.

filter_env: evita la fuga de variables de entorno globales

Por defecto, tu proceso de PM2 hereda todas las variables de entorno del shell padre. Eso incluye variables del sistema, variables de otras aplicaciones y cualquier cosa exportada en tu .bashrc. filter_env te permite definir una lista blanca de prefijos.

module.exports = {
  apps: [
    {
      name: "my-app",
      script: "./app.js",
      // Solo pasa las variables de entorno que empiezan por APP_ o DB_
      filter_env: ["APP_", "DB_"],
    },
  ],
};

Para descartar por completo todas las variables de entorno globales:

filter_env: true,

Es una función de seguridad. Evita la filtración accidental de secretos o variables de otros procesos. Consulta la sección de seguridad para más detalles.

increment_var: incrementa PORT automáticamente por instancia de clúster

Al ejecutar en modo clúster de PM2, cada instancia necesita su propio puerto. En lugar de fijar los puertos manualmente, usa increment_var:

module.exports = {
  apps: [
    {
      name: "api",
      script: "./api.js",
      instances: 4,
      exec_mode: "cluster",
      increment_var: "PORT",
      env: {
        PORT: 3000,
      },
    },
  ],
};

Esto produce: la instancia 0 recibe PORT=3000, la instancia 1 recibe PORT=3001, la instancia 2 recibe PORT=3002 y la instancia 3 recibe PORT=3003.

instance_var: personaliza NODE_APP_INSTANCE

PM2 define NODE_APP_INSTANCE para cada instancia del clúster (0, 1, 2, …). Esto entra en conflicto con la librería node-config, que usa la misma variable para sus propios fines. Renómbrala:

instance_var: "INSTANCE_ID",

Ahora cada instancia recibe INSTANCE_ID=0, INSTANCE_ID=1, etc. en lugar de NODE_APP_INSTANCE.

append_env_to_name: varios entornos en un mismo servidor

Si quieres ejecutar la misma aplicación en desarrollo y producción en una sola máquina:

module.exports = {
  apps: [
    {
      name: "my-app",
      script: "./app.js",
      append_env_to_name: true,
      env: { NODE_ENV: "development" },
      env_production: { NODE_ENV: "production" },
    },
  ],
};

Con pm2 start ecosystem.config.js --env production, PM2 nombra el proceso my-app-production. Sin la opción, es my-app-development. Ambos pueden ejecutarse simultáneamente.

Listar e inspeccionar variables de entorno en PM2

Para ver todas las variables de entorno de un proceso en ejecución:

# Por ID de proceso
pm2 env 0

# Por nombre de proceso
pm2 env my-app

Muestra todas las variables de entorno que el proceso puede ver, tanto las que definiste tú como todas las variables de sistema heredadas.

Para salida en JSON (útil para scripts):

pm2 jlist | jq '.[0].pm2_env'

Para una vista formateada de todos los procesos:

pm2 prettylist

Buenas prácticas de seguridad para las variables de entorno en PM2

Nunca escribas secretos en los archivos de ecosistema

Tu ecosystem.config.js debería estar bajo control de versiones. Eso significa que nunca debe contener contraseñas reales, claves de API ni tokens. En su lugar, inyéctalos en el momento del despliegue:

Opción 1: script envoltorio que carga un archivo .env

#!/bin/bash
# start-app.sh
set -a
source /etc/my-app/secrets.env
set +a
pm2 start ecosystem.config.js --env production

Opción 2: archivo de entorno de systemd

Si PM2 está gestionado por systemd (vía pm2 startup), puedes definir las variables en /etc/default/my-app y referenciarlas en el archivo de la unidad.

Opción 3: gestor de secretos

Para equipos y configuraciones más complejas, herramientas como Infisical, Doppler o HashiCorp Vault pueden inyectar secretos en el despliegue. Para configuraciones sencillas en solitario, un archivo .env con permisos restringidos (chmod 600) cargado por un script envoltorio suele ser suficiente.

Para quienes gestionan secretos en entornos con contenedores, consulta la gestión de secretos en Docker Compose para una comparación de enfoques.

Usar filter_env para limitar la exposición

Si tu servidor ejecuta varias aplicaciones con PM2, filter_env evita que una aplicación vea las variables de otra. El filtrado por prefijo es lo más práctico:

filter_env: ["MYAPP_"],

Ahora solo las variables que empiezan por MYAPP_ llegan a tu proceso. Todo lo demás se descarta.

Seguridad general del servidor

Las variables de entorno son solo una parte del panorama. Si aún no lo has hecho, revisa cómo securizar un servidor SSH en Linux. Si alguien obtiene acceso al shell, todas tus variables de entorno quedan expuestas, independientemente de lo bien que las gestiones en PM2.

Errores comunes con las variables de entorno de PM2 (y cómo evitarlos)

Conclusión

Las variables de entorno de PM2 se resumen en unas pocas reglas básicas:

1. Usa archivos de ecosistema para producción. Son explícitos, se pueden versionar y PM2 los relee al reiniciar.
2. Usa --update-env al cambiar variables definidas por CLI. Sin ella, pm2 restart es conservador y no recogerá los cambios.
3. Borra y vuelve a iniciar para los cambios en NODE_ENV. --update-env no funciona para las variables leídas al arrancar.
4. Usa filter_env para limitar la exposición. No dejes que tu aplicación herede todo el entorno del servidor.
5. Comprueba con pm2 env <id>. Verifica siempre lo que tu proceso ve realmente.

Para una visión completa de la gestión de procesos, consulta la guía completa para gestionar aplicaciones con PM2 y cómo elegir entre los modos fork y cluster. Y si tus dependencias de Node.js están desactualizadas, mantener tu entorno de Node.js al día merece la pena. PM2 7.x requiere Node.js 18+.

Si buscas un VPS asequible para ejecutar tus aplicaciones gestionadas con PM2, Hetzner Cloud ofrece una relación calidad-precio sólida en regiones de Europa y EE. UU. Hostinger VPS es otra opción económica con almacenamiento NVMe.

Los precios de los VPS subieron en todos los proveedores en 2026 — si estás reconsiderando un servidor alquilado, mira qué cambió y cuándo gana un mini PC.