Formatador .env

Para que serve formatar .env?

Em pouco tempo um arquivo .env vira uma bagunça. Deixá-lo formatado ajuda a comparar ambientes, revisar em PRs e flagrar duplicatas.

Linhas em branco e comentários (aquelas que abrem com #) ficam onde estavam. Valor que tem espaço no meio sai entre aspas.

Todo o processamento acontece localmente.

O arquivo .env e os princípios do Twelve-Factor App

O arquivo .env é uma convenção em texto puro para declarar variáveis de ambiente que o programa deve ler ao iniciar. Foi popularizado pela biblioteca dotenv original para Node.js e replicado em dezenas de ecossistemas: python-dotenv, godotenv, gem dotenv do Ruby, dotenvy em Rust, vlucas/phpdotenv em PHP e muitos outros. Docker Compose, GitHub Actions, Vercel, Netlify e Railway entendem o mesmo formato chave/valor, ainda que cada um faça o parsing de modo um pouco diferente.

O motivo pelo qual esse formato venceu é a metodologia Twelve-Factor App. O fator III ("Config") diz que tudo que provavelmente vai variar entre deploys (URLs de banco, tokens de API, hostnames, níveis de log) deve viver fora do código, em variáveis de ambiente. O teste decisivo é cruel: seu repositório deveria poder ser aberto como open-source a qualquer momento sem vazar uma única credencial. Um arquivo .env oferece um lugar agnóstico de linguagem e sistema operacional para manter esses valores no desenvolvimento local, enquanto deploys reais injetam as mesmas variáveis pelo cofre de segredos da plataforma.

O Twelve-Factor desencoraja explicitamente agrupar variáveis em conjuntos nomeados como development, staging ou production. Cada variável deve ser independente, para que a configuração escale linearmente conforme o número de deploys cresce, em vez de explodir combinatoriamente em perfis.

Sintaxe: KEY=VALUE, comentários, aspas e multilinha

Cada linha significativa é um par KEY=VALUE. Por convenção, as chaves usam UPPER_SNAKE_CASE e precisam seguir o padrão [A-Za-z_][A-Za-z0-9_]*. Hifens, acentos e dígito inicial são proibidos. Não pode haver espaços ao redor do sinal de igual: FOO = bar funciona em alguns parsers e quebra em outros — o seguro é sempre FOO=bar.

# Banco de dados
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD="s3nh4 com espaços"

# Comentários começam com #
API_BASE_URL=https://api.example.com   # comentário inline precisa de espaço
LOG_LEVEL=info

As aspas mudam o jeito como o valor é interpretado. Aspas duplas habilitam interpolação e sequências de escape (\n, \r, \t, \\): GREETING="Olá\nmundo" vira uma string de duas linhas. Aspas simples são literais: PATTERN='$VAR' permanece como os quatro caracteres $VAR. Valores sem aspas geralmente aceitam interpolação, mas exigem um espaço antes do # inline; sem o espaço, o # entra no valor.

Valores multilinha (chaves PEM, JWKS, JSON) são suportados de três jeitos, dependendo do parser:

# 1. Aspas duplas com \n
PRIVATE_KEY="-----BEGIN KEY-----\nMIIEvQI...\n-----END KEY-----\n"

# 2. Quebras de linha reais entre aspas duplas (dotenv >= 15)
PRIVATE_KEY="-----BEGIN KEY-----
MIIEvQI...
-----END KEY-----"

# 3. Bloco entre crases (dotenvx)
PRIVATE_KEY=`-----BEGIN KEY-----
MIIEvQI...
-----END KEY-----`

Carregamento por plataforma

• Node.js: require('dotenv').config() ou a flag nativa node --env-file=.env app.js.
• Python: from dotenv import load_dotenv; load_dotenv().
• Docker Compose: um .env ao lado do docker-compose.yml é lido automaticamente para substituição de variáveis; por serviço, use env_file:.
• GitHub Actions: cadastre os segredos nas configurações do repositório e exponha-os no workflow via env:.
• Vercel / Netlify / Railway / Fly.io: cole o conteúdo do seu .env pelo painel ou CLI; a plataforma injeta as variáveis no build e em runtime.
• Kubernetes: converta em ConfigMap (não sensível) ou Secret (sensível) e monte no pod como variáveis de ambiente.

Segurança: nunca comitar, sempre ignorar

Um .env com credenciais reais nunca deve chegar ao controle de versão. Adicione-o ao .gitignore desde o primeiro commit e versione um .env.example com valores fictícios, documentando quais variáveis o app espera. Segundo o relatório State of Secrets Sprawl da GitGuardian, milhões de credenciais vazam em commits públicos do GitHub todo ano, e o .env esquecido está entre os vetores mais comuns.

Para times, o .env puro não escala: não há log de acesso, nem rotação, nem controle por desenvolvedor. As alternativas maduras são:

• dotenv-vault / dotenvx — criptografa o .env em repouso com AES-GCM; você comita o blob cifrado e mantém uma única chave de decifragem fora do repositório.
• SOPS (Mozilla) — criptografa arquivos YAML/JSON/ENV usando AWS KMS, GCP KMS, Azure Key Vault, age ou PGP. Combina bem com GitOps.
• HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Doppler, Infisical — cofres centralizados com auditoria, rotação e IAM granular.

Boas práticas

• Use nomes em UPPER_SNAKE_CASE consistentes e agrupe por prefixo (DB_*, STRIPE_*, AWS_*).
• Valide as variáveis na inicialização com um schema (Zod, Joi, Pydantic, envalid) para que o app falhe alto e cedo quando uma chave obrigatória estiver faltando, em vez de quebrar silenciosamente em produção.
• Mantenha segredos fora dos artefatos de build: nunca os embuta em imagens Docker ou bundles de front-end; prefira injeção em runtime.
• Faça rotação periódica das credenciais e a cada offboarding.
• Documente cada variável no .env.example com um comentário de uma linha.

Erros comuns

• Espaços em torno do = (FOO = bar) — aceito em alguns parsers, rejeitado em outros.
• Aspas faltando em valores multilinha — tudo depois é engolido até a próxima aspa.
• BOM UTF-8 no início do arquivo — a primeira chave vira KEY e nunca casa.
• Cerquilha dentro de valor sem aspas (COLOR=#fff) — o parser interpreta como comentário; coloque entre aspas.
• Esperar interpolação em aspas simples (URL='https://$HOST') — o valor permanece literal.
• Chaves duplicadas — só a última (ou a primeira, dependendo do parser) prevalece.

FAQ

Existe uma especificação oficial do .env? Não. O formato é uma convenção de facto, compartilhada entre implementações com pequenas diferenças em aspas, escapes e interpolação. Teste sempre com o parser que você vai colocar em produção.

Posso ter vários arquivos .env? Sim — padrões comuns são .env, .env.local, .env.development e .env.production. Frameworks como Next.js, Vite e Rails carregam-nos em ordem documentada; consulte o manual da sua ferramenta.

Devo comitar o .env.example? Sim. Ele documenta as variáveis obrigatórias sem expor valores e permite que novos contribuidores copiem para .env e preencham os próprios segredos.

Variáveis de ambiente são realmente seguras? São mais seguras do que constantes no código, mas continuam legíveis por qualquer processo do mesmo usuário. Para produção, prefira um cofre com injeção em runtime para que o texto em claro nunca toque o disco.

O formatador altera meus valores? Não. Ele apenas normaliza espaços, ordena ou agrupa chaves, opcionalmente coloca aspas em valores com espaços e remove duplicatas. Os valores em si são preservados byte a byte.