O Que Sao Variaveis de Ambiente e Por Que Existem
Toda aplicacao precisa de informacoes para funcionar: o endereco do banco de dados, a chave de uma API, a senha de um servico. Essas informacoes mudam de um lugar para o outro. No seu computador, o banco e local. Na Vercel, o banco e na nuvem. Uma variavel de ambiente e uma forma de guardar esses valores fora do codigo, para que o mesmo app rode em qualquer lugar so trocando a configuracao.
🧠 Analogia: O Cofre Separado do Codigo
Imagine que o seu app e uma casa, e o codigo e a planta da casa. A planta voce pode mostrar para qualquer um, publicar na internet, colocar no GitHub. Mas a chave da porta voce nao desenha na planta. Voce guarda num cofre separado.
- •O codigo e a planta: igual em todo lugar, pode ser publico.
- •As variaveis de ambiente sao a chave no cofre: secretas, mudam por lugar.
- •Trocar a chave (config) nao exige reconstruir a casa (o app).
Como o codigo le uma variavel
Em vez de escrever o valor direto no codigo, voce le da variavel de ambiente. O nome consagrado e process.env no Node.js.
# ERRADO: segredo no codigo (qualquer um ve)
const apiKey = "sk-live-9f8a7b6c5d4e3f2a1b0c";
# CERTO: o codigo le a variavel de ambiente
const apiKey = process.env.API_KEY;
O codigo continua igual em todo lugar. Quem define o valor de API_KEY e o ambiente onde o app roda.
O Arquivo .env Local
No seu computador, o cofre tem um nome: o arquivo .env (com ponto na frente). E um arquivo de texto simples, com uma variavel por linha, no formato CHAVE=valor. Ele fica na raiz do projeto e nunca vai para o GitHub.
Criando o arquivo .env
# Na raiz do projeto, crie o arquivo
$ touch .env
$ nano .env
# Dentro do .env, uma variavel por linha:
API_KEY=sk-live-9f8a7b6c5d4e3f2a1b0c
DATABASE_URL=postgres://user:senha@host:5432/db
PORT=3000
Sem aspas, sem espaco em volta do =. Por convencao, os nomes ficam em MAIUSCULAS_COM_UNDERLINE.
Lendo o .env com dotenv
O Node.js nao le o arquivo .env sozinho. A biblioteca dotenv carrega o arquivo e coloca as variaveis em process.env.
# Instalar a biblioteca
$ npm install dotenv
added 1 package in 1s
# No topo do seu arquivo principal (index.js):
require('dotenv').config();
# Agora process.env.API_KEY funciona
console.log(process.env.PORT);
3000
Frameworks como Next.js e Vite ja leem o .env automaticamente, sem precisar do dotenv.
💡 Dica: Crie um .env.example
Como o .env nao vai para o GitHub, quem clonar o projeto nao sabe quais variaveis preencher. A solucao e criar um .env.example com as chaves mas sem os valores (ex: API_KEY=). Esse sim voce commita: ele serve de modelo, sem vazar segredo.
⚠️ Erro Comum
Problema: "Defini a variavel no .env mas process.env.API_KEY aparece como undefined."
Solucao: Geralmente sao tres causas: (1) esqueceu de chamar require('dotenv').config() no topo do arquivo; (2) o .env nao esta na raiz onde o app roda; (3) colocou espaco ou aspas no valor. Verifique os tres e reinicie o app (variaveis sao lidas so na inicializacao).
Variaveis no Vercel
Quando o app sobe para a Vercel, ele nao tem o seu .env local (que nem foi enviado). Entao voce precisa cadastrar as mesmas variaveis no painel da Vercel. Elas ficam guardadas com seguranca e sao injetadas no app a cada deploy. O melhor: a Vercel separa as variaveis por ambiente (Production, Preview, Development).
Abra as configuracoes do projeto
No painel da Vercel, escolha o projeto e va em Settings > Environment Variables.
Adicione cada variavel
Preencha o nome (Key) e o valor (Value), iguais ao seu .env.
# Exemplo de uma variavel
Key: API_KEY
Value: sk-live-9f8a7b6c5d4e3f2a1b0c
Escolha o ambiente
Marque onde a variavel vale: Production (site no ar), Preview (deploys de branch) e/ou Development (local com vercel dev). Voce pode ter um banco de testes no Preview e o banco real so na Production.
Faca um novo deploy
As variaveis sao aplicadas no proximo build. Se voce adicionou uma variavel depois do deploy, precisa fazer um Redeploy para ela entrar em vigor.
👁 O que voce vai ver na tela
Na pagina Environment Variables, cada variavel cadastrada aparece como uma linha. O valor fica oculto (mostrado como pontinhos) e voce ve em quais ambientes ela esta ativa:
# Lista de variaveis no painel
API_KEY •••••••• Production, Preview
DATABASE_URL •••••••• Production
NEXT_PUBLIC_URL myapp.com All Environments
No Next.js, variaveis com prefixo NEXT_PUBLIC_ ficam visiveis no navegador. Use so para valores que nao sao secretos (como a URL publica do site).
Variaveis no GitHub Actions
Se voce usa GitHub Actions para automatizar testes ou deploy, os scripts tambem precisam de segredos: token de deploy, chave de API, senha do banco. O GitHub guarda esses valores nos Secrets do repositorio. Eles ficam criptografados, ninguem consegue ler, e voce os usa dentro do workflow.
Cadastrando um Secret
No repositorio do GitHub, va em Settings > Secrets and variables > Actions e clique em New repository secret.
# Exemplo de secret cadastrado
Name: DEPLOY_TOKEN
Secret: ghp_xxxxxxxxxxxxxxxxxxxx
Depois de salvar, o GitHub nunca mais mostra o valor. Se esquecer, e so cadastrar de novo.
Usando o Secret no workflow
Dentro do arquivo do workflow (.github/workflows/deploy.yml), voce le o secret com a sintaxe ${{ secrets.NOME }}.
name: Deploy
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Fazer deploy
# injeta o secret como variavel de ambiente
env:
API_KEY: ${{ secrets.API_KEY }}
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: npm run deploy
Dentro do step, o app le process.env.API_KEY como sempre. O secret nunca aparece nos logs: o GitHub esconde o valor automaticamente.
💡 Dica: Secrets vs Variables
O GitHub tem duas abas: Secrets (valores secretos, escondidos para sempre) e Variables (valores nao-secretos, visiveis). Use Secrets para tokens, chaves e senhas. Use Variables (lidas com ${{ vars.NOME }}) para configuracoes publicas, como o nome do ambiente ou a regiao.
Seguranca: O Que NUNCA Commitar
A regra de ouro e simples: segredo nenhum vai para o Git. Quando voce comita um arquivo, ele entra no historico para sempre, e se o repositorio for publico, qualquer pessoa no mundo pode ver. Robos varrem o GitHub o dia inteiro procurando chaves vazadas para abusar delas. A defesa principal e o arquivo .gitignore.
O .gitignore protege o seu .env
O .gitignore e uma lista de arquivos que o Git deve ignorar. Adicione o .env nessa lista antes de qualquer commit.
# Conteudo do arquivo .gitignore
.env
.env.local
.env*.local
node_modules/
# Confirme que o Git esta ignorando:
$ git status
nothing to commit, working tree clean
# O .env NAO aparece na lista. Protegido.
✓ Pode commitar
- ✓O
.gitignore(a lista de exclusao) - ✓O
.env.example(so as chaves, sem valores) - ✓Codigo que le
process.env - ✓Config publica (URL do site, nome do app)
✗ NUNCA commitar
- ✗O arquivo
.envcom valores reais - ✗Chaves de API e tokens no codigo
- ✗Senhas de banco de dados
- ✗Arquivos de credencial (
.pem,.key, JSON de service account)
⚠️ Erro Comum
Problema: "Commitei o .env por engano antes de criar o .gitignore. Apaguei o arquivo e commitei de novo. Resolvido?"
Solucao: Nao. O valor continua no historico do Git e pode ser recuperado por qualquer um. Apagar agora nao adianta. Trate a chave como vazada: revogue e gere uma nova no servico (veja o topico 6). Reescrever o historico (com git filter-repo) ajuda, mas se ja foi para o GitHub publico, considere o segredo comprometido.
Rotacao de Secrets
Mesmo bem guardado, um segredo nao deve durar para sempre. Rotacionar e trocar a chave por uma nova de tempos em tempos, e revogar a antiga. Assim, se uma chave vazou sem voce perceber, ela tem um prazo de validade curto. E se voce sabe que vazou, a rotacao e imediata e obrigatoria.
🧠 Analogia: Trocar a Fechadura
Voce nunca saberia se um ex-funcionario fez copia da chave da sua casa. Por isso, ao trocar de inquilino, voce troca a fechadura: todas as copias antigas param de funcionar de uma vez. Rotacionar um secret e exatamente isso. A chave nova passa a valer; a velha vira lixo, mesmo que alguem tenha uma copia.
Gere a chave nova
No painel do servico (Supabase, Stripe, etc.), crie uma nova chave. A maioria deixa as duas chaves ativas por um tempo, para a troca nao quebrar o app.
Atualize em todos os lugares
Troque o valor no .env local, no painel da Vercel e nos Secrets do GitHub. Os tres precisam apontar para a chave nova.
# Lugares onde o segredo vive
.env (local)
Vercel > Settings > Environment Variables
GitHub > Settings > Secrets
Faca o redeploy e teste
Suba a nova versao e confirme que o app funciona com a chave nova. So depois passe para o ultimo passo.
Revogue a chave antiga
No painel do servico, apague ou desative a chave velha. A partir daqui, qualquer copia antiga para de funcionar. Esse e o passo que de fato fecha a porta.
✓ Boas praticas
- ✓Rotacionar segredos importantes a cada 60-90 dias
- ✓Revogar IMEDIATAMENTE qualquer chave que vazou
- ✓Usar chaves diferentes por ambiente (dev / prod)
- ✓Dar a cada chave so a permissao que ela precisa
✗ Evitar
- ✗Usar a mesma chave por anos sem trocar
- ✗Compartilhar segredos por chat ou e-mail
- ✗Reusar a chave de producao no ambiente de testes
- ✗Deixar a chave antiga ativa "por garantia"
🏆 Voce fechou a Trilha 2!
Voce ja sabe subir um app na Vercel, conectar um banco no Supabase, consumir APIs e agora guardar segredos com seguranca. Esse e o ciclo completo do deploy moderno: codigo no Git, app na nuvem, dados no banco e configuracao no cofre. Na proxima trilha, voce vai descer um nivel e aprender a rodar tudo no seu proprio servidor.
📚 Resumo do Modulo
Proxima Trilha:
Trilha 3 - Servidor Proprio (VPS, SSH, firewall e tokens: rode tudo na sua propria maquina na nuvem)