Guia de Variáveis de Ambiente e Gestão de Configuração para Web Apps

Inserir credenciais de banco de dados, chaves de API e segredos diretamente no código-fonte (hardcoding) é um dos erros mais graves e comuns no desenvolvimento web moderno. As variáveis de ambiente surgem como a solução definitiva para separar a configuração do código, permitindo que o mesmo sistema rode em desenvolvimento, homologação e produção com ajustes específicos para cada cenário.

O Princípio do 12-Factor App

A metodologia 12-Factor App, amplamente adotada na cultura Cloud Native, estabelece que a configuração de uma aplicação deve ser armazenada estritamente no ambiente, nunca no repositório. Os pilares principais incluem:

• Tokens, senhas de banco e chaves de acesso nunca devem ser commitados no controle de versão (Git).
• O código permanece idêntico em todos os deploys; apenas a configuração externa muda.
• As variáveis são injetadas no runtime (tempo de execução) para garantir isolamento e segurança.

Utilizando Arquivos .env

# Configurações de Banco de Dados
DATABASE_URL=postgres://usuario:senha@localhost:5432/meu_app
DATABASE_POOL_SIZE=10

# Chaves de API de Terceiros
STRIPE_SECRET_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xxxxx

# Ambiente e Porta
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

# Feature Flags (Alternadores de Funcionalidades)
ENABLE_NEW_CHECKOUT=true
ENABLE_DARK_MODE=false

Como Ler Variáveis de Ambiente

// Carrega o arquivo .env em desenvolvimento
import 'dotenv/config';

// Acessando as variáveis
const dbUrl = process.env.DATABASE_URL;
const port = parseInt(process.env.PORT || '3000', 10);
const isDev = process.env.NODE_ENV === 'development';

// Validação de variáveis obrigatórias no startup
const obrigatorias = ['DATABASE_URL', 'STRIPE_SECRET_KEY'];
for (const chave of obrigatorias) {
  if (!process.env[chave]) {
    throw new Error(`Variável de ambiente ausente: ${chave}`);
  }
}

// PHP Nativo
$dbUrl = getenv('DATABASE_URL');
$debug = getenv('APP_DEBUG') === 'true';

// Com a biblioteca vlucas/phpdotenv (via Composer)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['DATABASE_URL', 'APP_KEY'])->notEmpty();

// Acesso global via $_ENV
$apiKey = $_ENV['STRIPE_SECRET_KEY'];

Regra de Ouro: O Arquivo .gitignore

# NUNCA envie estes arquivos para o Git
.env
.env.local
.env.production
.env*.local

# SEMPRE envie o modelo (sem valores reais)
.env.example

Mantenha sempre um arquivo .env.example atualizado. Ele serve como documentação para outros desenvolvedores saberem quais variáveis a aplicação exige para funcionar, sem expor dados sensíveis.

DATABASE_URL=postgres://user:pass@host:port/db
STRIPE_SECRET_KEY=insira_sua_chave_aqui
NODE_ENV=development
PORT=3000

Configurações Específicas por Ambiente

• Desenvolvimento (Dev): Modo debug ativado, logs detalhados, banco de dados local e chaves de teste (sandbox).
• Homologação (Staging): Configurações idênticas à produção, mas com dados de teste para validação final.
• Produção (Prod): Debug desativado, logs mínimos (segurança), banco de dados de alta disponibilidade, certificados SSL e chaves reais.

Gerenciamento de Segredos em Escala

Para ambientes produtivos robustos, não utilize arquivos .env diretamente no servidor. Prefira soluções de gestão de segredos (Secrets Management):

• Secrets de Provedores Cloud: AWS Secrets Manager, Google Secret Manager ou Azure Key Vault.
• HashiCorp Vault: Ferramenta líder para gestão centralizada de segredos com auditoria.
• CI/CD Secrets: Variáveis criptografadas no GitHub Actions, GitLab CI ou painéis de plataformas como Vercel e Heroku.
• Docker/Kubernetes: Utilize Docker Secrets ou ConfigMaps/Secrets do Kubernetes para injeção nativa.

Erros Comuns para Evitar

• Enviar o .env para o Git: Caso aconteça, mude todas as senhas imediatamente, pois o histórico do Git manterá o registro.
• Usar chaves de produção em Dev: Nunca use chaves reais de pagamento ou e-mail durante o desenvolvimento local.
• Ignorar a validação: Se uma variável essencial falta, a aplicação deve falhar no boot (fail-fast) com uma mensagem clara.
• Espalhar process.env pelo código: Centralize o acesso às configurações em um único módulo ou classe de Config.