Boas Práticas de Segurança: Variáveis de Ambiente e Arquivos .env

Boas Práticas de Segurança: Variáveis de Ambiente e Arquivos .env — aula do módulo OpenRouter & Modelos Gratuitos, na trilha Provedores e Modelos Gratuitos…

Leitura de aproximadamente 5 minutos.

Módulo: OpenRouter & Modelos Gratuitos · Curso: Provedores e Modelos Gratuitos com OpenRouter & OpenCode · Formação: Formação Nível Zero: Ferramentas Essenciais e Gratuitas de IA e Código

Boas Práticas de Segurança: Variáveis de Ambiente e Arquivos .env

O que você vai aprender

1. O Risco Crítico de Escrever Chaves no Código

Quando alguém cria seu primeiro script para conversar com uma IA, o impulso mais comum é colar o texto da chave de API diretamente no meio do código:


// ATENÇÃO: NUNCA FAÇA ISSO EM NENHUM PROJETO!
const chaveOpenRouter = "sk-or-v1-abcdef1234567890abcdef1234567890";

Embora o programa funcione na sua máquina, essa prática representa uma vulnerabilidade grave. Quando você sincroniza seu projeto com o GitHub (utilizando os comandos git add, git commit e git push que aprendemos no módulo de Git), o arquivo que contém a chave é enviado para a nuvem pública.

Existem robôs automatizados na internet que escaneiam repositórios do GitHub a cada milissegundo em busca de textos com o formato sk-or-v1- ou sk-proj-. Se a sua chave for encontrada, invasores podem esgotar seus créditos em poucos minutos ou utilizá-la para atividades maliciosas.

2. A Solução: O que São Variáveis de Ambiente?

A regra de ouro da engenharia de software moderna é: separe o código-fonte da sua configuração e das suas credenciais.

O código-fonte (os arquivos .js, .py ou .html) define a lógica do sistema e deve ser compartilhado livremente com sua equipe ou no GitHub. Já as credenciais (senhas, chaves de API e conexões de banco de dados) pertencem exclusivamente ao ambiente da sua máquina física.

Para realizar essa separação, utilizamos Variáveis de Ambiente (do inglês Environment Variables). Uma variável de ambiente é uma informação armazenada na memória do sistema operacional que os programas conseguem ler durante a execução, sem que essa informação esteja escrita explicitamente dentro do arquivo do programa.


+-------------------------------------------------------------------------------+
|                       SEPARAÇÃO ENTRE CÓDIGO E CREDENCIAIS                    |
+-------------------------------------------------------------------------------+
|                                                                               |
|   SUA MÁQUINA LOCAL (Privada)                    GITHUB (Nuvem Pública)       |
|   ┌─────────────────────────────┐                ┌────────────────────────┐   |
|   │ Arquivo .env:               │                │ Repositório:           │   |
|   │ OPENROUTER_API_KEY=sk-...   │ (Bloqueado)    │                        │   |
|   │                             │ ──X─── NÃO vai │                        │   |
|   │ Arquivo .gitignore:         │                │ Arquivo .gitignore     │   |
|   │ .env                        │ ───────────────┼──> Arquivo .env.example│   |
|   │                             │                │ Código-fonte puro      │   |
|   │ Código-fonte (app.js):      │ ───────────────┼──> (app.js)            │   |
|   │ "process.env.OPENROUTER_KEY"│                │                        │   |
|   └─────────────────────────────┘                └────────────────────────┘   |
|                                                                               |
+-------------------------------------------------------------------------------+

3. O Padrão do Arquivo .env na Prática

Para não precisar configurar variáveis no painel do sistema operacional manualmente a cada reinicialização, a comunidade técnica utiliza um arquivo de texto simples chamado .env (lê-se "ponto-env", abreviação de environment).

Dentro da pasta raiz do seu projeto, você cria um arquivo com o nome exato .env contendo linhas no formato CHAVE=VALOR:


# Configurações locais do projeto (Arquivo .env)
OPENROUTER_API_KEY=sk-or-v1-abcdef1234567890abcdef1234567890
MODELO_PADRAO=qwen/qwen3.8-27b:free

Como os Programas Acessam essas Variáveis

No seu código-fonte, você passa a referenciar o nome da variável em vez do texto secreto:

Quando o programa é iniciado, a biblioteca do ambiente lê o arquivo .env local e injeta os valores na memória de execução de forma invisível.

4. O Arquivo .gitignore e o .env.example

Para garantir que o Git nunca rastreie o arquivo .env, incluímos uma linha com o nome dele no arquivo .gitignore:


# Arquivo .gitignore na raiz do projeto
node_modules/
.env
.env.local
*.log

O Arquivo .env.example

Como novos colaboradores (ou você mesmo em outro computador) saberão quais chaves o projeto necessita se o arquivo .env nunca sobe para o GitHub?

Criamos um arquivo de documentação pública chamado .env.example. Ele contém os nomes de todas as variáveis necessárias, mas com os valores em branco ou com exemplos fictícios:


# Exemplo de configuração (.env.example - este arquivo PODE ir para o GitHub)
OPENROUTER_API_KEY=sua_chave_do_openrouter_aqui
MODELO_PADRAO=qwen/qwen3.8-27b:free

5. Armadilhas Comuns e Como Evitar

[!WARNING]
Apagar o .env depois de commitar NÃO apaga o histórico: Se você criar um arquivo .env, fizer um git commit e só depois perceber que a chave subiu para o Git, simplesmente deletar o arquivo em um novo commit não remove a chave do histórico antigo do repositório. O Git funciona como uma máquina do tempo e mantém o registro de todas as versões anteriores. Se cometer esse engano, revogue a chave imediatamente no painel do OpenRouter e crie uma nova.

Exercício Prático

Vamos criar e blindar a estrutura de segurança de um projeto local:

1. Crie uma pasta de estudos: No terminal (Git Bash ou PowerShell), crie e acesse uma pasta de testes:


   mkdir projeto-seguro-teste
   cd projeto-seguro-teste

2. Inicialize o repositório Git:


   git init

3. Crie o arquivo de proteção .gitignore:


   echo ".env" > .gitignore

4. Crie o arquivo secreto .env:


   echo "OPENROUTER_API_KEY=sk-or-v1-chave-de-teste-12345" > .env

5. Crie o arquivo público de exemplo .env.example:


   echo "OPENROUTER_API_KEY=coloque_sua_chave_aqui" > .env.example

6. Valide a proteção: Execute o comando de verificação do Git:


   git status

Observe o resultado: o Git listará .gitignore e .env.example como novos arquivos rastreáveis, mas o arquivo .env estará totalmente invisível e protegido.

Outras aulas do módulo