Next.js carrega variáveis de ambiente dos arquivos .env, com uma regra de segurança importante: as variáveis são apenas do servidor por padrão, e apenas aquelas com o prefixo NEXT_PUBLIC_ são expostas ao navegador.
.env # loaded in all environments
.env.local # local overrides — GITIGNORED (put secrets here)
.env.development # only in `next dev`
.env.production # only in production builds
# .env.local
DATABASE_URL=postgres://...secret... # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com # exposed to the browser
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL; // ✅ works on the server
// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL; // ✅ works
const secret = process.env.DATABASE_URL; // ❌ undefined in the browser
Esta regra de prefixo é um recurso de segurança: evita que você envie acidentalmente senhas de banco de dados ou segredos de API para o cliente. Uma variável sem prefixo simplesmente não existe em pacotes de navegador.
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
Porque são embutidas no tempo de compilação, alterar um valor NEXT_PUBLIC_ exige uma reconstrução — e você nunca deve colocar segredos reais atrás do prefixo (eles seriam visíveis no pacote para qualquer pessoa).
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
O modelo apenas de servidor por padrão com a opção NEXT_PUBLIC_ é o protetor do Next.js contra vazamento de segredos para o cliente — um erro comum e grave.
Entender quais variáveis chegam ao navegador, que valores públicos são incorporados no tempo de compilação e onde armazenar segredos (.env.local ignorado) é essencial tanto para funcionalidade quanto para segurança.