blog
Fundamentos

Variáveis de ambiente: o segredo que todo dev precisa entender

Senhas no código? Nunca. Entenda o que são variáveis de ambiente, por que são essenciais e como usar sem complicação.

hidden: true

TL;DR

Variáveis de ambiente são configurações que ficam fora do código. Senhas, chaves de API, URLs de banco de dados — tudo isso deve viver em variáveis de ambiente, nunca hardcoded. É a diferença entre um app seguro e um desastre esperando acontecer.

hidden: true

O erro que todo vibecoder comete uma vez

Você tá construindo um app. Precisa conectar no banco de dados. E faz isso:

const db = new Database("postgresql://admin:senha123@localhost:5432/meubanco");

Funciona no localhost. Você faz commit. Faz push pro GitHub. E aí percebe: sua senha do banco está pública para o mundo inteiro.

Isso acontece mais do que você imagina. Bots vasculham o GitHub 24/7 procurando senhas commitadas. Em minutos, alguém pode acessar seu banco, seu Stripe, seu AWS.

Variáveis de ambiente existem para evitar isso.

O que são variáveis de ambiente?

São valores que existem no sistema operacional ou no servidor, não no código. Seu app lê esses valores quando precisa, mas eles nunca aparecem no repositório.

Em vez de:

const dbUrl = "postgresql://admin:senha123@db.exemplo.com:5432/prod";

Você faz:

const dbUrl = process.env.DATABASE_URL;

O valor real de DATABASE_URL existe apenas no ambiente onde o app roda — sua máquina, o servidor de produção, etc.

O arquivo .env

No desenvolvimento local, variáveis de ambiente ficam em um arquivo chamado .env na raiz do projeto:

# .env
DATABASE_URL=postgresql://admin:senha123@localhost:5432/meubanco
STRIPE_SECRET_KEY=sk_test_abc123
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Frameworks como Next.js, Vite e Nuxt leem esse arquivo automaticamente. Você não precisa fazer nada especial.

Regra de ouro: O .env NUNCA vai pro Git. Sempre adicione ao .gitignore:

# .gitignore
.env
.env.local
.env.production

.env.example: o mapa do tesouro

Se o .env não vai pro Git, como outros devs (ou você no futuro) sabem quais variáveis configurar?

Crie um .env.example com os nomes mas sem os valores reais:

# .env.example
DATABASE_URL=
STRIPE_SECRET_KEY=
NEXT_PUBLIC_API_URL=

Esse arquivo vai pro Git. Serve como documentação: "essas são as variáveis que o projeto precisa".

Variáveis públicas vs secretas

Algumas variáveis são sensíveis (senhas, chaves), outras não (URL pública da API).

No Next.js, existe uma convenção:

  • NEXT_PUBLIC_* → visível no navegador (frontend)
  • Sem prefixo → só no servidor (backend)
# Segredo — só o servidor vê
STRIPE_SECRET_KEY=sk_live_xxx
 
# Público — o navegador pode ver
NEXT_PUBLIC_APP_URL=https://meuapp.com

Nunca coloque chaves secretas em variáveis públicas. Se começa com NEXT_PUBLIC_, qualquer pessoa pode ver inspecionando o código no navegador.

Como funciona em produção

No localhost, o .env cuida de tudo. Mas em produção, não existe arquivo .env — as variáveis são configuradas diretamente no servidor ou plataforma.

Na plataforma de deploy

Cada plataforma tem sua forma de gerenciar variáveis:

# Veloz
$ veloz env set DATABASE_URL="postgresql://user:pass@host:5432/db"
$ veloz env set STRIPE_SECRET_KEY="sk_live_xxx"
$ veloz env list
 
# Vercel
$ vercel env add DATABASE_URL
 
# Railway
# Pelo dashboard → Variables

As variáveis ficam criptografadas na plataforma e são injetadas no ambiente quando o app roda. Seguro e prático.

Por que não usar .env em produção?

  1. Segurança — arquivos podem ser expostos acidentalmente
  2. Praticidade — não precisa acessar o servidor para mudar um valor
  3. Auditoria — plataformas registram quem mudou o quê e quando
  4. Separação — cada ambiente (dev, staging, prod) tem seus próprios valores

O fluxo correto

Desenvolvimento:
  código lê process.env.DATABASE_URL
  valor vem do arquivo .env local

Produção:
  código lê process.env.DATABASE_URL (mesmo código!)
  valor vem da plataforma de deploy (Veloz, Vercel, etc.)

O código é idêntico nos dois ambientes. Só os valores mudam. Isso é o poder das variáveis de ambiente.

Checklist de segurança

  • ✅ .env no .gitignore
  • ✅ .env.example no repositório (sem valores reais)
  • ✅ Nenhuma senha ou chave hardcoded no código
  • ✅ Variáveis secretas sem prefixo NEXT_PUBLIC_
  • ✅ Variáveis de produção configuradas na plataforma de deploy
  • ✅ Chaves diferentes para dev e produção (nunca reusar)

E se eu já commitei uma senha?

Acontece. E mudar a senha no próximo commit não resolve — o histórico do Git guarda tudo.

O que fazer:

  1. Troque a senha/chave imediatamente no serviço afetado
  2. Revogue a chave antiga (Stripe, AWS, etc.)
  3. Remova do histórico do Git (com git filter-branch ou BFG Repo Cleaner)
  4. Adicione .env ao .gitignore para nunca mais acontecer

Melhor prevenir. Configure o .gitignore antes do primeiro commit.

hidden: true

FAQ

Posso commitar meu arquivo .env no Git?

Nunca. O .env contém segredos como senhas e chaves de API. Adicione .env ao seu .gitignore e use .env.example (sem valores reais) para documentar quais variáveis são necessárias.

Como passo variáveis de ambiente para produção?

Depende da plataforma. Na maioria, você configura pelo dashboard ou CLI. No Veloz, por exemplo: veloz env set DATABASE_URL=postgresql://... — e a variável fica disponível para seu app em produção.

Qual a diferença entre variáveis de ambiente e hardcoded?

Hardcoded é quando o valor está escrito direto no código e visível para qualquer pessoa. Variável de ambiente é um valor externo que o código lê em tempo de execução — não aparece no repositório e pode mudar sem alterar código.