Como usar variáveis de ambiente no Node.js para proteger configurações

Variáveis de ambiente no Node.js são uma forma simples de tirar senhas, URLs e configurações do código-fonte. Na prática, o programa lê esses valores pelo objeto process.env, enquanto cada ambiente — desenvolvimento, teste ou produção — fornece os próprios dados.

O caminho mais direto hoje é criar um arquivo .env local e iniciar o projeto com node --env-file=.env. O recurso nativo começou a ser distribuído no Node.js 20.6.0, e a documentação atual também lista APIs para carregar e interpretar arquivos desse tipo.

O que são variáveis de ambiente no Node.js?

São valores associados ao ambiente em que o processo está rodando. O Node.js disponibiliza esses valores em process.env, um objeto que já vem preenchido com as variáveis recebidas do sistema e que também pode ser alterado pelo programa.

Imagine uma aplicação que precisa acessar um banco de dados. Em vez de escrever a senha diretamente em server.js, você guarda o valor fora do código e lê apenas o nome da variável:

const databaseUrl = process.env.DATABASE_URL;

if (!databaseUrl) {
  throw new Error('DATABASE_URL não foi configurada');
}

Assim, o mesmo código pode usar um banco local no computador do desenvolvedor e outro banco na hospedagem. A aplicação não precisa ser editada a cada implantação.

Como configurar um arquivo .env

Na raiz do projeto, crie um arquivo chamado .env. Cada linha deve representar um par de nome e valor:

PORT=3000
DATABASE_URL="postgres://usuario:senha@localhost:5432/loja"
API_BASE_URL=https://api.exemplo.com
NODE_ENV=development

Depois, inicie o arquivo principal com o carregador nativo:

node --env-file=.env server.js

Dentro do programa, os valores ficam disponíveis em process.env.PORT, process.env.DATABASE_URL e assim por diante. Variáveis de ambiente chegam como texto; por isso, converta números e valide valores obrigatórios antes de abrir portas ou conectar serviços.

Exemplo completo com validação

const port = Number(process.env.PORT || 3000);
const apiBaseUrl = process.env.API_BASE_URL;

if (!apiBaseUrl) {
  throw new Error('API_BASE_URL não foi configurada');
}

if (!Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error('PORT precisa ser um número entre 1 e 65535');
}

console.log(`Servidor configurado na porta ${port}`);

O teste é simples: execute o comando, confira se o processo inicia sem erro e altere temporariamente PORT para confirmar que a aplicação está lendo o arquivo certo.

Como evitar que o .env vaze para o Git

O arquivo .env deve ficar fora do repositório quando contiver senhas, tokens ou chaves privadas. Adicione-o ao .gitignore antes do primeiro git add:

.env
.env.*
!.env.example

Você pode manter um .env.example sem segredos para documentar os nomes esperados:

PORT=3000
DATABASE_URL=
API_BASE_URL=https://api.exemplo.com

Isso não protege uma chave que já foi enviada ao Git. Se um segredo aparecer em um commit, trate-o como comprometido: revogue ou troque a credencial e remova o arquivo do fluxo de desenvolvimento. Para um passo a passo complementar sobre esse problema em automações, veja também como proteger chaves de API no n8n sem expor segredos.

Como usar variáveis de ambiente em produção

Em produção, prefira cadastrar os valores no painel da hospedagem, no serviço de secrets ou no mecanismo de configuração do contêiner. O objetivo é entregar DATABASE_URL, tokens e chaves ao processo sem colocar esses dados no código ou em uma imagem pública.

O arquivo .env é conveniente para desenvolvimento, mas não é um cofre. Ele é apenas um arquivo de texto. Permissões do servidor, backup, logs e acesso ao painel continuam importantes. Também evite imprimir process.env inteiro no console: um log pode acabar em um serviço de monitoramento acessível a outras pessoas.

Erros comuns e como corrigir

• “A variável está undefined”: confirme o nome, o diretório em que o comando foi executado e se o processo foi iniciado com --env-file=.env.
• O número não funciona: lembre que o valor chega como string e use Number(), além de validar o resultado.
• O segredo foi parar no Git: troque a credencial imediatamente; adicionar o arquivo ao .gitignore não apaga o histórico.
• A chave apareceu no navegador: qualquer variável enviada ao JavaScript do cliente deixa de ser secreta. Segredos devem ser usados no servidor e acessados por uma API própria.
• O comando não reconhece --env-file: verifique a versão com node --version. O suporte nativo foi introduzido no Node.js 20.6.0; projetos mais antigos podem exigir uma biblioteca específica ou uma atualização planejada.

Vale a pena usar variáveis de ambiente?

Sim, especialmente quando o projeto tem mais de um ambiente ou usa serviços externos. Elas reduzem a chance de publicar credenciais, tornam o deploy repetível e permitem alterar uma configuração sem editar o código. Mas não substituem validação, rotação de chaves, controle de acesso e cuidado com logs.

Perguntas frequentes

O Node.js lê arquivos .env sozinho?

O Node.js moderno pode carregar o arquivo pela opção --env-file ou por APIs próprias. Apenas criar o arquivo não garante que ele será lido: o processo precisa ser iniciado de uma forma que carregue esse conteúdo.

Posso colocar senha no .env?

Você pode usar um .env local para desenvolvimento, mas não deve versioná-lo nem tratá-lo como cofre. Em produção, use o mecanismo de segredos ou variáveis protegidas da hospedagem.

Por que process.env.PORT é texto?

Variáveis de ambiente são recebidas como texto. Converta o valor com Number() e valide o resultado antes de usá-lo como porta, limite ou outra configuração numérica.

Variáveis de ambiente funcionam no frontend?

Ferramentas de frontend podem substituir valores durante o build, mas tudo que for enviado ao navegador pode ser lido pelo usuário. Não coloque senhas ou chaves privadas no bundle do cliente.