Busque em todas as páginas da documentação
Configuração é tudo o que um processo Node.js precisa para se comportar corretamente em um determinado ambiente - URLs de banco de dados, toggles de recursos, timeouts, chaves de API - que não está embutido no próprio código-fonte. Ela existe porque o mesmo aplicativo compilado precisa rodar de forma diferente em um laptop, um runner de CI, um cluster de staging e em produção, sem que ninguém toque no código entre esses ambientes.
Esta página é o modelo mental por trás do restante da seção. Noções Básicas de Configuração mostra o código em funcionamento - um módulo de configuração tipado, arquivos .env, esquemas Zod - e as outras páginas aprofundam em partes específicas (gerenciadores de segredos, flags de recursos, injeção de ambiente). Aqui, o objetivo é entender por que a configuração é estruturada da maneira que é: como uma fronteira entre código e ambiente, com segredos como a região mais rigorosa dessa fronteira.
.env versus um gerenciador de segredos, depurar "funciona localmente, quebra em produção" e raciocinar sobre o raio de explosão caso um valor de configuração vaze.Antes que a configuração fosse uma disciplina própria, as configurações viviam onde fosse conveniente: uma constante perto do topo de um arquivo, um config.json verificado no repositório, um valor que alguém se lembrava de mudar antes de implantar.
Essa abordagem falha no momento em que um aplicativo precisa rodar em mais de um lugar, porque "conveniente" e "seguro para commitar" são barras diferentes, e um valor que é aceitável em um repositório público (uma porta padrão) não é o mesmo tipo de valor que um que não é (uma senha de banco de dados).
A metodologia twelve-factor app nomeou a correção claramente: armazene a configuração no ambiente, não no código.
Uma maneira útil de visualizar: o aplicativo compilado é um eletrodoméstico selado, e a configuração é o conjunto de botões em seu painel traseiro, lidos uma vez quando ele é conectado.
Os internos do eletrodoméstico nunca mudam entre um laptop e um cluster de produção - apenas as posições dos botões mudam, e esses são fornecidos de fora, por quem estiver conectando (um shell, um orquestrador, um gerenciador de segredos).
// Anti-padrão: valor embutido na compilação
const DB_HOST = "prod-db.internal";
// Twelve-factor: valor lido do ambiente na inicialização
const DB_HOST = process.env.DB_HOST;Segredos não são um mecanismo diferente de configuração - são configurações com uma política mais rigorosa anexada.
Uma chave de API e um nível de log são ambos "dados externos lidos na inicialização", mas um deles causa um incidente se aparecer em uma linha de log ou em um repositório público, e o outro não.
Tratar segredos como "configuração mais controle de acesso" em vez de um sistema totalmente separado mantém o modelo mental simples, ao mesmo tempo que permite que as equipes apliquem controles reais - criptografia em repouso, trilhas de auditoria, credenciais de curta duração - apenas onde esses controles realmente valem seu custo.
A forma prática da configuração do Node.js é process.env: cada variável de ambiente definida para o processo está disponível como uma string nesse objeto, e nada mais sobre o aplicativo em execução muda com base de onde essas strings vieram.
Esse último ponto é mais importante do que parece: process.env.DATABASE_URL é lido da mesma forma, quer o valor tenha sido digitado em um shell, injetado por um ConfigMap do Kubernetes, ou buscado em um gerenciador de segredos e mesclado durante a inicialização.
Isso é o que torna as fontes de configuração intercambiáveis sem tocar na lógica de negócios - a fonte de uma configuração (um arquivo .env localmente, um env injetado pela plataforma em produção, uma busca no vault para segredos) é uma decisão de infraestrutura, enquanto o consumo dessa configuração é um único caminho de código inalterado.
Esse único caminho de consumo geralmente é um esquema, não leituras dispersas de process.env.
Ler process.env.PORT diretamente em doze arquivos diferentes significa que doze lugares podem interpretar um valor ausente ou malformado de maneiras diferentes - um pode travar, um pode usar um padrão silenciosamente, um pode converter uma string de uma forma que outro não faz.
Centralizar cada configuração através de um único esquema validado (comumente Zod nesta pilha) significa que existe exatamente um lugar que decide o que "válido" significa, e exatamente um momento - a inicialização - em que essa decisão é aplicada.
import { z } from "zod";
const envSchema = z.object({
DATABASE_URL: z.string().url(),
PORT: z.coerce.number().default(3000),
});
// parse() lança imediatamente se DATABASE_URL estiver ausente ou malformado -
// o processo nunca aceita tráfego com configuração em que não pode confiar
export const config = envSchema.parse(process.env);Essa chamada parse() é o mecanismo por trás do fail-fast: em vez de uma URL de banco de dados ausente aparecer como um erro de tempo de execução confuso na primeira solicitação que toca no banco de dados, ela aparece como uma falha imediata e legível antes que o processo sequer vincule uma porta.
Segredos adicionam mais um passo a esse fluxo sem alterar sua forma: uma busca no gerenciador de segredos acontece antes da validação do esquema, mesclando valores descriptografados no mesmo process.env (ou um objeto equivalente) do qual a configuração comum lê, para que a camada de validação trate um segredo buscado e uma variável de ambiente simples identicamente.
A fronteira entre "config" e "segredo" nem sempre é óbvia nas bordas, e errar tem custos diferentes em cada direção.
Um PUBLIC_WEB_URL é seguro para logar e seguro em um ConfigMap; um DATABASE_URL incorpora uma senha e não é - mas muitos valores ficam entre eles, como um nome de host interno que não é secreto, mas revela a topologia da infraestrutura se vazar. A regra prática que escala em uma equipe é tratar por padrão qualquer coisa que pareça uma credencial, string de conexão ou chave como um segredo, e exigir uma razão explícita para relaxar isso, em vez do contrário.
Onde a fonte de um valor reside muda suas propriedades operacionais, não apenas sua localização de armazenamento:
| Fonte | História de rotação | Trilha de auditoria | Melhor ajuste |
|---|---|---|---|
Arquivo .env (apenas local) | Manual, impulsionado pelo desenvolvedor | Nenhum | Apenas desenvolvimento local, nunca commitado |
| Env injetado pela plataforma (ConfigMap, painel de env PaaS) | Redeploy necessário para mudar | Nível da plataforma, muitas vezes grosseiro | Configurações não secretas, implantações simples |
| Gerenciador de segredos (Vault, AWS SSM, Doppler) | Pode rotacionar independentemente de deploys | Granular, por acesso | Credenciais, chaves de API, qualquer coisa que a conformidade se importe |
Essa tabela está realmente descrevendo uma única tendência: à medida que um valor se torna mais sensível, a infraestrutura ao redor dele deve se tornar mais cara de construir e mais barata de operar corretamente - um gerenciador de segredos custa mais esforço de configuração do que um arquivo .env, mas ele se paga em rotação e auditabilidade que um arquivo plano estruturalmente não pode fornecer.
A validação na inicialização também muda a superfície de falha de um pipeline de implantação inteiro, não apenas de um processo. Um esquema que rejeita configurações malformadas transforma o que seria uma chamada às 2 da manhã - um serviço se comportando silenciosamente mal porque DB_POOL_MAX foi parseado como NaN - em uma falha na sonda de prontidão durante uma implantação de rotina, capturada pela CI ou por uma implantação canary antes que ela atinja tráfego real. É por isso também que a validação de configuração pertence o mais próximo possível do início do processo: quanto mais cedo um valor ruim for capturado, menor será o raio de explosão e mais barmo o conserto.
Flags de recursos complicam ainda mais o quadro, introduzindo um segundo eixo: flags estáticas e controladas pelo ambiente (um redeploy para mudar) se comportam exatamente como a configuração comum, mas flags dinâmicas e por usuário (LaunchDarkly, Unleash) são dados em tempo de execução buscados de um serviço, não dados de inicialização do processo - confundir os dois leva as equipes a esperar mudanças instantâneas nas flags de algo que na verdade está embutido no ambiente implantado.
.env nunca é commitado.PORT que chegou como "abc", o que um padrão sozinho não pegará.process.env é bom; o risco está em como um segredo chegou lá e quem mais pode ler o ambiente do processo - não no mecanismo da variável.Qualquer valor que muda entre ambientes e não é determinado pelo próprio código - URLs de banco de dados, portas, timeouts, flags de recursos, chaves de API de terceiros e níveis de log são exemplos típicos.
Isso acopla o código implantável à identidade do ambiente, o que significa que um único artefato de build não pode mais ser promovido inalterado de staging para produção - o objetivo do twelve-factor é que o mesmo build rode em todos os lugares, e apenas os dados do ambiente mudam.
O sistema operacional ou o runtime do contêiner passa variáveis de ambiente para o processo Node quando ele inicia, a partir de qualquer coisa que as definiu - um export de shell, um flag -e do Docker, um ConfigMap/Secret do Kubernetes, ou um gerenciador de segredos que mescla valores durante um script de inicialização antes que o esquema do aplicativo seja executado.
Sem ela, um valor ausente ou malformado surge mais tarde e indiretamente - uma URL de banco de dados undefined trava profundamente em um pool de conexões com um stack trace confuso. Com ela, envSchema.parse(process.env) lança imediatamente na inicialização com uma mensagem nomeando o campo ausente exato, antes que o processo aceite qualquer tráfego.
Funcionalmente sim - ele flui através do mesmo padrão de leitura na inicialização e validação única como qualquer outra configuração. O que difere é a política envolvida em torno dele: controle de acesso mais rigoroso, rotação e uma trilha de auditoria de quem acessou qual segredo e quando.
Quando os segredos rotacionam com mais frequência do que os deploys acontecem, quando a conformidade exige uma trilha de auditoria de quem acessou quais segredos, ou quando vários serviços precisam de acesso com escopo de caminho a um conjunto compartilhado de credenciais que variáveis de ambiente simples não conseguem expressar.
Cada nova configuração tem que passar por esse arquivo único, que pode se tornar um gargalo ou um ímã de conflitos de merge em uma equipe grande - a solução geralmente é dividir o esquema em seções por domínio dentro de um único módulo, não abandonar a centralização.
Uma flag estática é lida do ambiente na inicialização, então mudá-la requer um redeploy como qualquer outro valor de configuração; uma flag dinâmica é buscada de um serviço em execução no momento da solicitação, então ela pode mudar instantaneamente sem tocar no processo implantado.
Valores não secretos (um nível de log, uma URL pública, o estado de uma flag de recurso) geralmente são seguros para registrar; qualquer coisa que conceda acesso se interceptada - strings de conexão, chaves de API, tokens - deve ser redigida em serializadores de log antes que chegue a uma linha de log.
Um valor ausente é ausência - um padrão de esquema pode muitas vezes cobri-lo com segurança. Um valor inválido é a presença da forma errada - uma PORT definida como "abc" - e nenhum padrão corrige isso; apenas a validação explícita do esquema a captura, e é por isso que padrões e validação resolvem problemas diferentes.
Não - os tipos do TypeScript desaparecem em tempo de compilação, e process.env é um objeto de strings simples em tempo de execução que o TypeScript não pode verificar se realmente corresponde à sua forma declarada. A validação em tempo de execução (Zod ou similar) é o que impõe o contrato que os tipos sozinhos apenas descrevem.
Versões da Stack: Esta página foi escrita para Node.js 24 LTS e TypeScript 5.6+.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026