Variáveis de ambiente e segredos: como usar o .env sem vazar senhas

Por que variáveis de ambiente

O mesmo código roda em lugares diferentes: na sua máquina, no servidor de testes e em produção, cada um com seu banco e suas chaves. As variáveis de ambiente separam a configuração do código, e os segredos ficam fora do repositório. O arquivo .env é só uma forma prática de definir essas variáveis na sua máquina.

• Ponha .env no .gitignore e faça commit de um .env.example, com os nomes das variáveis e valores de exemplo.
• Em produção, defina as variáveis no painel da hospedagem ou no gerenciador de segredos, não em um arquivo no servidor.
• Para segredos próprios, como a chave que assina sessões, gere valores longos e aleatórios, por exemplo com o gerador de senha.

Em Node.js, sem biblioteca

Desde o Node.js 20.6, node --env-file=.env app.js carrega o arquivo sem instalar o pacote dotenv. A função exigirEnv faz o programa parar na inicialização quando falta uma variável, com uma mensagem clara, em vez de quebrar depois, no meio de uma requisição, com um erro difícil de entender.

// Node.js 20.6+: node --env-file=.env app.js, sem instalar nada.
// Ou no próprio código (Node.js 20.12+): process.loadEnvFile('.env')

function exigirEnv(nome) {
  const valor = process.env[nome];
  if (valor === undefined || valor === '') {
    throw new Error(`Falta a variável de ambiente ${nome}. Confira o arquivo .env.`);
  }
  return valor;
}

// Falha logo na inicialização, e não no meio de uma requisição
const config = {
  bancoUrl: exigirEnv('DATABASE_URL'),
  porta: Number(process.env.PORT ?? 3000),
};

Em Python e PHP

Os dois leem variáveis do ambiente sem pacote extra. Para carregar um arquivo .env, o costume é o python-dotenv no Python e o vlucas/phpdotenv no PHP.

import os

# Para ler o arquivo .env, use o pacote python-dotenv:
#   from dotenv import load_dotenv
#   load_dotenv()


def exigir_env(nome: str) -> str:
    valor = os.environ.get(nome, "")
    if not valor:
        raise RuntimeError(f"Falta a variável de ambiente {nome}. Confira o arquivo .env.")
    return valor


# Falha logo na inicialização, e não no meio de uma requisição
CONFIG = {
    "banco_url": exigir_env("DATABASE_URL"),
    "porta": int(os.environ.get("PORT", "3000")),
}

<?php
// Para ler o arquivo .env, use o pacote vlucas/phpdotenv (o Laravel já usa)

function exigirEnv(string $nome): string
{
    $valor = getenv($nome);
    if ($valor === false || $valor === '') {
        throw new RuntimeException("Falta a variável de ambiente $nome. Confira o arquivo .env.");
    }
    return $valor;
}

$config = [
    'bancoUrl' => exigirEnv('DATABASE_URL'),
    'porta' => (int) (getenv('PORT') ?: 3000),
];

No front-end, nada é segredo

Tudo que vai para o navegador pode ser lido por qualquer pessoa, inclusive o JavaScript do site. Os frameworks deixam isso explícito com prefixos: só as variáveis com VITE_ (Vite), NEXT_PUBLIC_ (Next.js), PUBLIC_ (Astro) ou REACT_APP_ (Create React App) entram no código do navegador, e por isso nunca devem guardar segredos.

Se o front-end precisa de uma API com chave secreta, a chamada deve passar pelo seu servidor, que guarda a chave e repassa só o resultado.

Se um segredo vazou

• Troque o segredo imediatamente: gere uma chave nova, atualize os ambientes e revogue a antiga. Essa é a única medida que resolve.
• Apagar o arquivo ou reescrever o histórico do Git não basta: repositórios públicos são vasculhados por robôs em poucos minutos, e o valor pode já ter sido copiado.
• Confira nos registros do serviço se a chave foi usada por alguém.
• Ative a proteção contra envio de segredos do GitHub (secret scanning), que bloqueia o push quando reconhece uma chave conhecida.