Variáveis de ambiente e arquivo .env: senhas fora do código

Escrever a senha do banco ou a chave de uma API direto no código parece prático. Funciona, até o dia em que você sobe o projeto para o GitHub, manda o arquivo para um colega ou cola o trecho numa IA para pedir ajuda. Dali em diante, o segredo está fora do seu controle. Variáveis de ambiente existem para evitar isso.

O que são variáveis de ambiente

São pares de nome e valor que pertencem ao ambiente em que o programa roda, e não ao código dele. Por exemplo, um nome como CHAVE_DA_API associado a um valor longo. O programa, ao iniciar, pergunta ao sistema “qual é o valor de CHAVE_DA_API?” e usa a resposta.

Vantagens:

• Segredos fora do código. O mesmo código pode ser publicado sem expor nada.
• Configuração por ambiente. Você usa um banco de testes no seu computador e outro em produção, sem alterar o código, só o valor da variável.
• Troca fácil. Se uma chave vaza, você muda o valor sem mexer no projeto.

Onde guardar na prática

Há três lugares comuns:

1. Variáveis do próprio sistema operacional: configuradas nas opções do sistema ou no terminal. Servem, mas são trabalhosas para vários projetos.
2. Arquivo .env: um arquivo de texto na pasta do projeto, com uma linha por variável no formato NOME=valor. É o método mais popular em desenvolvimento.
3. Painel da plataforma de hospedagem: em serviços de deploy, você cadastra as variáveis no painel do projeto (veja deploy explicado).

Como criar e usar um arquivo .env

Passo a passo:

1. Na pasta raiz do projeto, crie um arquivo chamado exatamente .env (com o ponto na frente).
2. Escreva uma variável por linha, sem espaços ao redor do sinal de igual. Exemplo de formato: NOME_DA_VARIAVEL=valor.
3. Antes de tudo, abra o arquivo .gitignore e inclua uma linha com .env. Assim o Git ignora o arquivo e ele não vai ao repositório.
4. Instale a biblioteca que lê o arquivo. No Python, é a python-dotenv. No Node.js, a dotenv, e algumas versões e frameworks já leem o .env sem pacote extra.
5. No código, carregue o arquivo e leia a variável. No Python, depois de carregar o .env, use os.getenv com o nome da variável. No JavaScript com Node, use process.env seguido do nome.

O arquivo .env.example

Como o .env real não vai para o repositório, quem baixar o projeto não sabe quais variáveis criar. A solução é um arquivo .env.example, que vai para o Git com os nomes das variáveis e valores falsos ou em branco. Quem for usar o projeto copia o modelo para .env e preenche com seus próprios valores. É uma documentação simples e muito útil.

O que colocar em variáveis de ambiente

• chaves de API (de serviços de IA, de e-mail, de pagamento);
• usuário, senha e endereço do banco de dados;
• segredos usados para assinar sessões e tokens;
• senhas de e-mail para envio automático (veja enviar e-mails automáticos com Python);
• configurações que mudam por ambiente, como o endereço do site em teste e em produção.

Coisas que não são segredo, como o nome do site ou um idioma padrão, podem ficar no código ou em arquivo de configuração comum.

Erros comuns

• Variável com valor vazio: o programa lê “nada” e falha de forma confusa. Verifique se a variável existe ao iniciar e mostre um erro claro.
• Nome digitado diferente: CHAVE_API contra CHAVE_DA_API. Um erro de digitação basta.
• Espaços e aspas: dependendo da biblioteca, aspas e espaços extras viram parte do valor. Confira o que a documentação aceita.
• Esquecer de reiniciar: o programa só lê as variáveis ao iniciar. Se mudou o .env, reinicie.
• Rodar de outra pasta: o arquivo .env é procurado em um local específico. Se rodar o script de outra pasta, ele pode não ser encontrado.
• Variáveis no navegador: em frameworks de front-end, só algumas variáveis são enviadas ao navegador (em geral com um prefixo definido pelo framework), e tudo o que for enviado fica público. Nunca use esse tipo para segredos.

Um exemplo completo de organização

Veja como fica um projeto bem arrumado, descrito em palavras:

• na raiz, o arquivo .env com as variáveis reais, que só existe na sua máquina e no servidor;
• ao lado, o arquivo .env.example com os mesmos nomes e valores fictícios, que vai para o Git;
• no .gitignore, uma linha com .env;
• no código, apenas a leitura das variáveis pelo nome;
• no painel da hospedagem, as variáveis cadastradas para produção, com valores diferentes dos de teste.

Com essa estrutura, qualquer pessoa clona o projeto, copia o modelo, preenche os próprios valores e roda. Os segredos nunca aparecem no histórico, e trocar uma chave vira um ajuste de poucos segundos.

Cuidados além do básico

• Uma chave por projeto e por ambiente. Isso limita o estrago se uma vazar.
• Permissões mínimas. Se a chave permite só leitura, crie-a só com leitura.
• Não cole o .env em chats, e-mails ou IAs. Antes de pedir ajuda, apague os valores.
• Em servidores, restrinja quem pode ler o arquivo.
• Rotacione chaves com regularidade e quando alguém sai da equipe.

Para aprofundar o lado defensivo, leia segurança básica em código: os erros mais comuns. Se está montando seu primeiro projeto, crie o .gitignore e o .env.example desde o primeiro dia: é um hábito simples que evita um dos acidentes mais frequentes de quem programa.