Busca en todas las páginas de la documentación
La configuración es todo lo que un proceso de Node.js necesita para comportarse correctamente en un entorno dado (URLs de bases de datos, conmutadores de características, tiempos de espera, claves de API) que no está integrado en el propio código fuente. Existe porque la misma aplicación compilada tiene que ejecutarse de manera diferente en un portátil, un ejecutor de CI, un clúster de staging y producción, sin que nadie toque el código entre esos entornos.
Esta página es el modelo mental detrás del resto de la sección. Conceptos básicos de configuración muestra el código funcional (un módulo de configuración tipado, archivos .env, esquemas Zod), y las otras páginas profundizan en piezas específicas (gestores de secretos, indicadores de características, inyección de entorno). Aquí, el objetivo es comprender por qué la configuración está estructurada de la manera en que lo está: como un límite entre el código y el entorno, con los secretos como la región más estricta de ese límite.
.env frente a un gestor de secretos, depurar "funciona localmente, falla en producción" y razonar sobre el radio de impacto si un valor de configuración se filtra.Antes de que la configuración fuera una disciplina propia, los ajustes residían donde fuera conveniente: una constante cerca de la parte superior de un archivo, un config.json registrado en el repositorio, un valor que alguien recordaba cambiar antes de desplegar.
Ese enfoque se rompe en el momento en que una aplicación necesita ejecutarse en más de un lugar, porque "conveniente" y "seguro para confirmar" son barras diferentes, y un valor que está bien en un repositorio público (un puerto predeterminado) no es el mismo tipo de valor que uno que no lo está (una contraseña de base de datos).
La metodología de la aplicación de doce factores nombró la solución claramente: almacenar la configuración en el entorno, no en el código.
Una forma útil de imaginarlo: la aplicación compilada es un electrodoméstico sellado, y la configuración es el conjunto de diales en su panel trasero, leídos una vez cuando se enchufa.
Los componentes internos del electrodoméstico nunca cambian entre un portátil y un clúster de producción; solo cambian las posiciones de los diales, y estas se suministran desde el exterior, por lo que sea que esté haciendo la conexión (un shell, un orquestador, un gestor de secretos).
// Antipatrón: el valor está integrado en la compilación
const DB_HOST = "prod-db.internal";
// Doce factores: el valor se lee del entorno al inicio
const DB_HOST = process.env.DB_HOST;Los secretos no son un mecanismo diferente de la configuración, son configuración con una política más estricta adjunta.
Una clave de API y un nivel de registro son ambos "datos externos leídos al inicio", pero uno de ellos causa un incidente si aparece en una línea de registro o en un repositorio público, y el otro no.
Tratar los secretos como "configuración más control de acceso" en lugar de como un sistema completamente separado mantiene el modelo mental simple al mismo tiempo que permite a los equipos aplicar controles reales (cifrado en reposo, pistas de auditoría, credenciales de corta duración) solo donde esos controles realmente valen su costo.
La forma práctica de la configuración de Node.js es process.env: cada variable de entorno establecida para el proceso está disponible como una cadena en ese objeto, y nada más sobre la aplicación en ejecución cambia en función de dónde provengan esas cadenas.
Este último punto importa más de lo que parece: process.env.DATABASE_URL se lee idénticamente si el valor se escribió en un shell, se inyectó mediante un ConfigMap de Kubernetes, o se obtuvo de un gestor de secretos y se fusionó durante el arranque.
Esto es lo que hace que las fuentes de configuración sean intercambiables sin tocar la lógica de negocio: la fuente de una configuración (un archivo .env localmente, un entorno inyectado por la plataforma en producción, una obtención de vault para secretos) es una decisión de infraestructura, mientras que el consumo de esa configuración es una única e inmutable ruta de código.
Esa única ruta de consumo suele ser un esquema, no lecturas dispersas de process.env.
Leer process.env.PORT directamente en doce archivos diferentes significa que doce lugares pueden interpretar un valor faltante o mal formado de manera diferente: uno podría fallar, otro podría usar un valor predeterminado silenciosamente, otro podría coercionar una cadena de una manera que otro no.
Centralizar cada configuración a través de un esquema validado (comúnmente Zod en esta pila) significa que hay exactamente un lugar que decide qué significa "válido", y exactamente un momento (el arranque) en el que se aplica esa decisión.
import { z } from "zod";
const envSchema = z.object({
DATABASE_URL: z.string().url(),
PORT: z.coerce.number().default(3000),
});
// parse() lanza un error inmediatamente si DATABASE_URL falta o está mal formada -
// el proceso nunca acepta tráfico con una configuración en la que no puede confiar
export const config = envSchema.parse(process.env);Esa llamada a parse() es el mecanismo detrás del fallo rápido: en lugar de que una URL de base de datos faltante aparezca como un error de tiempo de ejecución confuso en la primera solicitud que toca la base de datos, aparece como un fallo inmediato y legible antes de que el proceso vincule un puerto.
Los secretos añaden un paso más a este flujo sin cambiar su forma: una obtención del gestor de secretos ocurre antes de la validación del esquema, fusionando los valores descifrados en el mismo process.env (o un objeto equivalente) del que lee la configuración ordinaria, de modo que la capa de validación trata un secreto obtenido y una variable de entorno simple de manera idéntica.
El límite entre "configuración" y "secreto" no siempre es obvio en los extremos, y equivocarse tiene diferentes costos en cada dirección.
Una PUBLIC_WEB_URL es segura para registrar y segura en un ConfigMap; una DATABASE_URL incrusta una contraseña y no lo es, pero muchos valores se encuentran en el medio, como un nombre de host interno que no es secreto pero revela la topología de la infraestructura si se filtra. La regla práctica que se aplica a todo un equipo es asumir por defecto que cualquier cosa que parezca una credencial, una cadena de conexión o una clave es un secreto, y requerir una razón explícita para relajar esa regla, en lugar de lo contrario.
El lugar donde reside la fuente de un valor cambia sus propiedades operativas, no solo su ubicación de almacenamiento:
| Fuente | Historia de rotación | Pista de auditoría | Mejor ajuste |
|---|---|---|---|
Archivo .env (solo local) | Manual, impulsado por el desarrollador | Ninguna | Solo desarrollo local, nunca se confirma |
| Entorno inyectado por la plataforma (ConfigMap, panel de entorno PaaS) | Requiere redespliegue para cambiar | Nivel de plataforma, a menudo grueso | Configuraciones no secretas, despliegues simples |
| Gestor de secretos (Vault, AWS SSM, Doppler) | Puede rotar independientemente de los despliegues | Granular, por acceso | Credenciales, claves de API, cualquier cosa que le importe al cumplimiento |
Esa tabla describe realmente una única tendencia: a medida que un valor se vuelve más sensible, la infraestructura que lo rodea debe volverse más costosa de construir y más barata de operar correctamente; un gestor de secretos cuesta más esfuerzo de configuración que un archivo .env, pero lo compensa en rotación y auditabilidad que un archivo plano estructuralmente no puede proporcionar.
La validación en tiempo de arranque también cambia la superficie de fallo de toda una pipeline de despliegue, no solo de un proceso. Un esquema que rechaza una configuración mal formada convierte lo que habría sido una alerta a las 2 a.m. (un servicio que se comporta mal silenciosamente porque DB_POOL_MAX se analizó como NaN) en una sonda de preparación fallida durante un despliegue rutinario, detectada por CI o un lanzamiento canary antes de que llegue al tráfico real. Esta es también la razón por la que la validación de la configuración debe estar lo más cerca posible del inicio del proceso: cuanto antes se detecte un valor incorrecto, menor será el radio de impacto y más barata será la solución.
Los indicadores de características complican aún más el panorama al introducir un segundo eje: los indicadores estáticos, impulsados por el entorno (un redespliegue para cambiar) se comportan exactamente como la configuración ordinaria, pero los indicadores dinámicos, por usuario (LaunchDarkly, Unleash) son datos en tiempo de ejecución obtenidos de un servicio, no datos de inicio del proceso en absoluto; confundir los dos lleva a los equipos a esperar cambios instantáneos de los indicadores de algo que en realidad está integrado en el entorno desplegado.
.env nunca se confirma.PORT que llegó como "abc", lo que un valor predeterminado por sí solo no detectará.process.env en sí mismo está bien; el riesgo está en cómo llegó un secreto allí y quién más puede leer el entorno del proceso, no el mecanismo de la variable.Cualquier valor que cambie entre entornos y no esté determinado por el propio código: URLs de bases de datos, puertos, tiempos de espera, conmutadores de características, claves de API de terceros y niveles de registro son ejemplos típicos.
Eso acopla el código desplegable a la identidad del entorno, lo que significa que un único artefacto de construcción ya no puede promoverse sin cambios de staging a producción; el objetivo principal de los doce factores es que la misma construcción se ejecute en todas partes, y solo los datos del entorno cambien.
El sistema operativo o el tiempo de ejecución del contenedor pasa las variables de entorno al proceso de Node cuando se inicia, desde quien las haya establecido: una exportación de shell, un indicador -e de Docker, un ConfigMap/Secret de Kubernetes, o un gestor de secretos que fusiona valores durante un script de arranque antes de que se ejecute el esquema de la aplicación.
Sin ella, un valor faltante o mal formado aparece más tarde e indirectamente: una URL de base de datos undefined falla en lo profundo de un pool de conexiones con un rastreo de pila confuso. Con ella, envSchema.parse(process.env) lanza un error inmediatamente al inicio con un mensaje que nombra el campo exacto que falta, antes de que el proceso acepte cualquier tráfico.
Funcionalmente sí, fluye a través del mismo patrón de lectura al inicio y validación única que cualquier otra configuración. Lo que difiere es la política que lo rodea: un control de acceso más estricto, rotación y una pista de auditoría de quién lo obtuvo y cuándo.
Cuando los secretos rotan con más frecuencia de lo que ocurren los despliegues, cuando el cumplimiento requiere una pista de auditoría de quién accedió a qué secreto, o cuando varios servicios necesitan acceso con ámbito de ruta a un conjunto compartido de credenciales que las variables de entorno de plataforma simples no pueden expresar.
Cada nueva configuración tiene que pasar por ese único archivo, lo que puede convertirse en un cuello de botella o un imán de conflictos de fusión en un equipo grande; la solución suele ser dividir el esquema en secciones por dominio dentro de un módulo, no abandonar la centralización.
Un indicador estático se lee del entorno al inicio, por lo que cambiarlo requiere un redespliegue como cualquier otro valor de configuración; un indicador dinámico se obtiene de un servicio en ejecución en el momento de la solicitud, por lo que puede cambiar instantáneamente sin tocar el proceso desplegado en absoluto.
Los valores no secretos (un nivel de registro, una URL pública, un estado de indicador de característica) son generalmente seguros para registrar; cualquier cosa que otorgaría acceso si se interceptara (cadenas de conexión, claves de API, tokens) debe ser redactada en los serializadores de registro antes de que llegue a una línea de registro.
Un valor faltante es ausencia; un valor predeterminado de esquema a menudo puede solucionarlo de forma segura. Un valor inválido es la presencia de la forma incorrecta (un PORT establecido en "abc"), y ningún valor predeterminado lo soluciona; solo la validación explícita del esquema lo detecta, por lo que los valores predeterminados y la validación resuelven problemas diferentes.
No, los tipos de TypeScript desaparecen en tiempo de compilación, y process.env es un objeto de cadenas simple en tiempo de ejecución que TypeScript no puede verificar que realmente coincida con la forma declarada. La validación en tiempo de ejecución (Zod o similar) es lo que impone el contrato que los tipos por sí solos solo describen.
Versiones de la pila: Esta página fue escrita para Node.js 24 LTS y TypeScript 5.6+.
Revisado por Chris St. John·Última actualización: 15 jul 2026