Por que o .env importa tanto e como tratá-lo bem

Publicado em 2026-09-12 por frfrand

Las claves que más se filtran no se roban: se suben sin querer. Tres costumbres que evitan casi todos esos sustos, y qué hacer cuando una credencial ya estuvo en un commit.

As credenciais que mais vazam não são roubadas com um ataque sofisticado. Elas são enviadas para um repositório sem querer.

Há empresas inteiras dedicadas a escanear repositórios públicos em busca de chaves. Uma credencial de um provedor de nuvem publicada por engano é detectada e usada em minutos, não em dias.

Por que existe o .env

A ideia vem de uma convenção de design de aplicações: a configuração que muda entre ambientes não vai no código, vai no ambiente.

O mesmo código precisa ser capaz de rodar na sua máquina, em staging e em produção, alterando apenas variáveis. Isso obriga a tirar do código tudo o que é específico de um ambiente: strings de conexão, chaves de API, endereços de serviços, segredos de assinatura.

O arquivo .env é simplesmente uma forma conveniente de carregar essas variáveis quando você está desenvolvendo. Em produção, muitas vezes nem é necessário o arquivo: as variáveis são injetadas pelo sistema que executa seu serviço.

As três práticas

1. .gitignore antes do primeiro commit.

echo ".env" >> .gitignore

A ordem importa. Se você adicionar depois, o arquivo já estará no histórico e removê-lo de lá é muito mais trabalho.

Uma verificação que vale a pena conhecer:

git check-ignore -v .env

Se não imprimir nada, não está ignorado, por mais que você pense que sim.

2. Permissões 600.

chmod 600 .env

Sólo seu usuário lê isso. Em um servidor com vários usuários ou vários serviços, isso não é teórico: é o que impede que o processo de outro aplicativo leia suas credenciais.

3. Um .env.example versionado.

Um arquivo com todas as chaves e nenhum valor:

DATABASE_URL= STRIPE_SECRET_KEY= JWT_SECRET=

Esse sim vai para o repositório. Serve como documentação viva de qual configuração o projeto precisa e evita o clássico de alguém clonar o repositório e perder duas horas descobrindo quais variáveis estão faltando.

Se uma chave já esteve em um commit

Aqui está o erro mais caro, porque parece resolvido e não está.

Apagar a chave do arquivo e fazer um novo commit não serve. A chave continua no histórico do repositório. Quem tiver o repositório, ou cloná-lo se for público, pode recuperá-la com um comando.

A única coisa que resolve de verdade é rotacionar a credencial: gerar uma nova e revogar a antiga.

Reescrever o histórico (com git filter-repo ou similar) pode ser desejável além disso, especialmente se o repositório for público, mas é secundário. Enquanto a credencial antiga continuar válida, o problema existe.

Ordem correta: rotacionar primeiro, limpar depois.

Um par de coisas a mais

Nem todo segredo é uma variável de ambiente. Para equipes grandes ou requisitos mais rígidos existem gerenciadores de segredos, com rotação automática e registro de acessos. Para a maioria dos projetos, variáveis de ambiente bem tratadas são suficientes.

Cuidado com os logs. É fácil, em uma sessão de depuração, imprimir toda a configuração e que isso fique em um arquivo de log que depois é compartilhado.

Cuidado com o frontend. Qualquer variável que termine no pacote que é enviado para o navegador é pública, mesmo que se chame SECRET. Se tem que ser segredo, vive no backend.

No ArduMaker, as variáveis de ambiente de um deploy são configuradas pelo painel e viajam para o serviço sem ficar escritas no repositório nem no histórico de comandos.