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

> Senhas de banco, chaves de API e tokens não devem ficar no código: o lugar deles é em variáveis de ambiente, que mudam entre a sua máquina, o teste e a produção. Este guia mostra como ler essas variáveis e o arquivo .env em Node.js, Python e PHP, por que um segredo no front-end nunca é segredo e o que fazer quando uma chave vaza no Git.

- Endereço oficial: https://pradev.com.br/guias/variaveis-de-ambiente-e-segredos-env
- Tipo: Guia
- Publicado em: 2026-10-01
- Atualizado em: 2026-10-01
- Autor: Leonardo Gaertner (https://pradev.com.br/sobre)
- Ferramentas: [Gerador de Senha](https://pradev.com.br/gerador-de-senha)

## 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](https://pradev.com.br/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.

```javascript
// 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),
};
```

_JavaScript_

## 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.

```python
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")),
}
```

_Python_

```php
<?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),
];
```

_PHP_

## 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.

## Perguntas frequentes

### Preciso do pacote dotenv no Node.js?

Não, a partir do Node.js 20.6: rode node --env-file=.env app.js. No próprio código, desde o Node.js 20.12, process.loadEnvFile(".env") faz o mesmo.

### Posso colocar uma chave de API em VITE_ ou NEXT_PUBLIC_?

Só se ela puder ser pública. Essas variáveis vão para o JavaScript do navegador, e qualquer pessoa consegue ler. Chaves secretas devem ficar no servidor.

### O que fazer se eu subi o .env para o GitHub?

Troque todos os segredos que estavam no arquivo, porque eles podem já ter sido copiados. Depois remova o arquivo, ponha .env no .gitignore e, se quiser, limpe o histórico. Limpar o histórico sem trocar as chaves não resolve.

### Devo fazer commit do .env.example?

Sim. Ele mostra quais variáveis o projeto precisa, com valores de exemplo, e ajuda quem clona o repositório a configurar o ambiente. Ele não deve ter valores reais.

## Fontes

- [Node.js: --env-file](https://nodejs.org/api/cli.html#--env-filefile)
- [The Twelve-Factor App: configuração](https://12factor.net/pt_br/config)

## Guias relacionados

- [Como gerar senha segura em código (sem Math.random)](https://pradev.com.br/guias/como-gerar-senha-segura-em-codigo): Por que Math.random não serve para senhas, como evitar o viés do módulo e como gerar senhas seguras em JavaScript, Python e PHP, com código testado.
- [Como guardar senhas: por que não usar SHA-256 e o que usar](https://pradev.com.br/guias/como-guardar-senhas-com-hash): Por que MD5 e SHA-256 não servem para senhas e como guardar senhas com scrypt, bcrypt ou Argon2 em Node.js, Python e PHP, com sal e código testado.