Variáveis de ambiente resolvem um problema recorrente: o mesmo código precisa se comportar de forma diferente em desenvolvimento, teste e produção. Em vez de editar o código a cada deploy, você define valores fora dele. Este guia mostra o caminho direto para configurar variáveis de ambiente no seu projeto, com passos práticos e armadilhas comuns.
Passo 1: identifique o que deve virar variável
Nem tudo precisa de variável. Comece listando o que muda entre ambientes: URLs de API, chaves de acesso, portas, níveis de log, flags de feature. Um critério simples: se o valor é sensível ou varia conforme o ambiente, ele entra. Se é fixo e não sensível, pode ficar no código.
Erro comum: transformar tudo em variável, criando um arquivo gigante e difícil de manter. Comece com o mínimo e adicione conforme a necessidade.
Passo 2: escolha o mecanismo de leitura
Cada linguagem tem seu jeito. Em Node.js, use process.env.NOME_DA_VARIAVEL. Em Python, os.environ.get('NOME_DA_VARIAVEL'). Em shells Unix, exporte no terminal ou no arquivo de perfil. O mecanismo é padronizado: o sistema operacional injeta os valores no processo.
Dica: defina um valor padrão na leitura. process.env.PORTA || 3000 evita crash quando a variável não existe.
Passo 3: crie um arquivo .env para desenvolvimento
O padrão de mercado é o arquivo .env na raiz do projeto, com o formato CHAVE=valor. Para ler esse arquivo, use uma biblioteca como dotenv (Node) ou python-dotenv (Python). Isso facilita a vida de quem chega no projeto: copiou o exemplo, ajustou, rodou.
Erro comum: versionar o .env no repositório. Isso expõe segredos. A prática correta é versionar apenas um .env.example com valores fictícios e documentar quais variáveis são obrigatórias.
Passo 4: separe ambientes de forma explícita
Muitos projetos precisam de valores diferentes por ambiente. Em vez de um único .env, use arquivos como .env.development, .env.test e .env.production, carregando o arquivo certo conforme o contexto. Frameworks como Next.js e Vite já trazem esse suporte nativo.
Ressalva: não crie variações sutis entre ambientes. Se a diferença é apenas uma URL, mantenha uma variável só. Quanto menos arquivos, menor a chance de erro.
Passo 5: trate segredos com cuidado extra
Variáveis de ambiente não são criptografia. Elas apenas escondem valores do código, mas quem tem acesso ao servidor pode lê-las. Para segredos de produção, considere um cofre (como AWS Secrets Manager ou HashiCorp Vault) que injeta os valores no processo sem persistir em arquivo.
Dica prática: nunca imprima o valor de uma variável sensível em logs. Se precisar debugar, mostre apenas se está definida ou não.
Passo 6: valide as variáveis no boot
No início da aplicação, verifique se todas as variáveis obrigatórias existem. Se faltar alguma, falhe rápido com uma mensagem clara. Isso evita erros obscuros no meio da execução, quando um valor undefined causa uma falha difícil de rastrear.
Um contraexemplo comum: o app inicia sem a chave da API e só quebra quando um usuário faz login. Validar no boot teria evitado isso.
Checklist do que você fez
- Listou os valores que mudam entre ambientes
- Definiu o mecanismo de leitura da sua linguagem
- Criou um
.envlocal e um.env.exampleversionado - Separou arquivos por ambiente, se necessário
- Tratou segredos sem expor em logs ou repositório
- Validou as variáveis obrigatórias no início da aplicação
FAQ
Variáveis de ambiente são seguras?
Elas são mais seguras que hardcode no código, mas não são à prova de falhas. Quem tem acesso ao servidor pode lê-las. Para segredos de produção, use cofres que injetam valores em memória.
Posso usar um único .env para todos os ambientes?
Tecnicamente sim, mas não é recomendado. Valores de produção e desenvolvimento raramente são os mesmos, e misturá-los aumenta o risco de usar configuração errada.
Como faço para não versionar o .env?
Adicione .env ao seu .gitignore. Versionar apenas o .env.example com valores fictícios é o padrão aceito.
O que acontece se uma variável não existir?
Depende da leitura. Se você usa process.env.CHAVE e o valor é undefined, o app pode quebrar. Sempre defina um valor padrão ou valide no boot.
Variáveis de ambiente funcionam em front-end?
Funcionam, mas com ressalvas. No front-end, os valores são embutidos no bundle e ficam visíveis no navegador. Nunca coloque segredos reais em variáveis de front-end.
Preciso de uma biblioteca para usar variáveis de ambiente?
Para ler do sistema operacional, não. A biblioteca é necessária apenas para carregar o arquivo .env em desenvolvimento. Em produção, você pode definir as variáveis diretamente no ambiente.
O fluxo descrito aqui resolve a maioria dos projetos. O próximo passo é automatizar a validação com testes que garantam que as variáveis obrigatórias existem antes do deploy.