Variáveis de Ambiente: Guia para Desenvolvedores

Variáveis de Ambiente: Configuração Feita Certo

Chaves de API, URLs de banco de dados e feature flags hardcodadas são a causa #1 de incidentes de segurança em times pequenos. Variáveis de ambiente resolvem isso separando configuração do código. Seu app lê DATABASE_URL ao invés de conter postgres://admin:password123@prod-db:5432.

Por Que Variáveis de Ambiente

A metodologia 12-factor app diz melhor: armazene config no ambiente. Benefícios:

• Segurança: Segredos não ficam no histórico git
• Flexibilidade: Mesmo código roda em dev, staging e prod com configs diferentes
• Simplicidade: Sem formatos complexos de arquivo de config para parsear

O Arquivo .env

A maioria dos frameworks suporta um arquivo .env na raiz do projeto:

# .env — NUNCA commite este arquivo
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-here
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_API_URL=https://api.example.com
NODE_ENV=development
PORT=3000

Carregue no seu app:

// Node.js — dotenv (mais comum)
import 'dotenv/config';
// ou
require('dotenv').config();

console.log(process.env.DATABASE_URL);
// "postgres://user:pass@localhost:5432/mydb"

# Python — python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()
db_url = os.getenv('DATABASE_URL')

Convenções de Nomenclatura

Crítico: Apenas variáveis com o prefixo específico do framework são expostas ao browser. Nunca coloque segredos em variáveis NEXT_PUBLIC_ ou VITE_ — elas estarão no seu bundle JavaScript.

Hierarquia de Arquivos de Ambiente

A maioria dos frameworks carrega env files nesta prioridade (posterior sobrescreve anterior):

.env                # Valores padrão, commitado no repo (sem segredos!)
.env.local          # Overrides locais, gitignored
.env.development    # Específico de desenvolvimento
.env.production     # Específico de produção
.env.test           # Específico de testes

Segredos em CI/CD

Nunca coloque segredos reais em arquivos .env que são deployados. Use o gerenciamento de segredos da sua plataforma CI/CD:

# GitHub Actions
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
    steps:
      - run: npm run deploy

# Docker Compose
services:
  app:
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    # Ou de um arquivo:
    env_file:
      - .env.production

Validação na Inicialização

Não espere um crash em runtime para descobrir que falta uma env var. Valide na inicialização:

// TypeScript com zod
import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(['development', 'production', 'test']),
});

export const env = envSchema.parse(process.env);
// Lança exceção imediatamente se alguma variável estiver faltando ou inválida

# Python com pydantic
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    jwt_secret: str
    port: int = 3000
    debug: bool = False

    class Config:
        env_file = '.env'

settings = Settings()  # Valida na instanciação

Erros Comuns

• Commitar .env no git. Adicione ao .gitignore antes do primeiro commit. Verifique com git log -- .env.
• Usar env vars para dados estruturados. ALLOWED_ORIGINS=http://localhost:3000,https://myapp.com funciona, mas para config complexa, use um arquivo de config que lê env vars.
• Formatos .env diferentes entre ferramentas. Algumas ferramentas precisam de aspas, outras não. KEY="value" e KEY=value se comportam diferente em shell vs dotenv.
• Esquecer de reiniciar. Env vars são lidas na inicialização do processo. Mudar o .env requer reiniciar o servidor.

Gerencie seus env files: Formatador Env — ordene, desduplicar e valide seus arquivos .env.