Capítulo 303 de 456

Environment Variables

Core Idea

Next.js carrega .env* automaticamente em process.env; variáveis prefixadas com NEXT_PUBLIC_ são inlineadas no bundle do browser em build time, as demais só existem no servidor.

Key Concepts

  • .env: carregado automaticamente pro Node.js runtime, usável em getStaticProps/getServerSideProps/API routes.
  • @next/env: pacote pra carregar as mesmas env vars fora do runtime do Next.js (ex.: config de ORM, test runner), via loadEnvConfig(projectDir).
  • Referência entre variáveis: $VARIABLE dentro de .env* expande o valor de outra variável (escapar com \$ se quiser o literal).
  • NEXT_PUBLIC_ prefix: única forma de expor uma env var ao browser; o valor é hard-coded no bundle no next build, não muda depois em runtime.
  • Lookups dinâmicos não são inlineados: process.env[varName] ou env.NEXT_PUBLIC_X (via variável intermediária) não funcionam, só a referência direta e estática process.env.NEXT_PUBLIC_X.
  • Runtime env vars: pra valores que mudam por ambiente sem rebuild, usar getServerSideProps (só server) em vez de NEXT_PUBLIC_.
  • .env.test: ambiente extra além de development/production; .env.local não é carregado em testes, garantindo defaults consistentes.
  • Ordem de carregamento (para na primeira encontrada): process.env → .env.$(NODE_ENV).local → .env.local (não em test) → .env.$(NODE_ENV) → .env.

Code Examples

TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER
  • O que demonstra: expansão de variável dentro do próprio .env (TWITTER_URL vira https://x.com/nextjs).
// NÃO será inlineado, porque usa variável
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
  • O que demonstra: lookup dinâmico quebra a substituição em build time do Next.js.

Reference Tables

OrdemFonte
1process.env
2.env.$(NODE_ENV).local
3.env.local (ignorado se NODE_ENV=test)
4.env.$(NODE_ENV)
5.env
VersãoMudança
v9.4.0Suporte a .env e NEXT_PUBLIC_ introduzido

Anti-patterns

  • Commitar arquivos .env* com segredo: create-next-app já ignora por padrão no .gitignore, manter assim.
  • Esperar NEXT_PUBLIC_ mudar sem rebuild: valor é congelado em build time; promover a mesma imagem/slug entre ambientes não muda esses valores.
  • Setar Cache-Control esperando runtime env: pra valor realmente dinâmico por ambiente, usar getServerSideProps ou API própria, nunca NEXT_PUBLIC_.

Key Takeaways

  1. Só NEXT_PUBLIC_* chega ao browser, e isso acontece em build time (valor fixo, não runtime).
  2. @next/env + loadEnvConfig é o jeito oficial de reusar as mesmas env vars fora do Next.js runtime (ORM configs, testes).
  3. .env.test ignora .env.local de propósito, pra testes serem determinísticos entre execuções.
  4. A ordem de precedência sempre para na primeira fonte que definir a variável.

Connects To

  • ch297 CI Build Caching: variáveis de ambiente também entram na chave de cache de CI em alguns setups.
AnteriorDraft ModePróximoForms