Variáveis de ambiente no Next.js: .env, NEXT_PUBLIC_ | We.Inc
Como o Next.js carrega arquivos .env, em que ordem, o que o NEXT_PUBLIC_ realmente faz no build e como ler valores em runtime. Cole o seu .env para ver o que chega ao navegador.
O Next.js lê os arquivos .env da raiz do projeto para dentro de process.env. Por padrão, as variáveis ficam só no servidor. Coloque o prefixo NEXT_PUBLIC_ em um nome e o Next.js copia o valor para o JavaScript do navegador durante o next build, então ele fica público e congelado até você fazer um novo build. Nunca coloque um segredo atrás desse prefixo.
Ordem de carregamento: o primeiro arquivo que define uma variável vence
Ordem
Origem
Observações
Valores já definidos pelo shell ou pelo host sempre vencem
.env.$(NODE_ENV).local
Por exemplo, .env.development.local
.env.local
Ignorado quando NODE_ENV é test
.env.$(NODE_ENV)
Por exemplo, .env.production
.env
Padrões compartilhados por todos os ambientes
Cole abaixo o conteúdo de um arquivo .env. O verificador separa cada variável em só no servidor ou enviada ao navegador, e aponta nomes públicos que parecem segredos. Tudo roda nesta página; nada do que você cola é enviado.
Cole as linhas do seu .env na caixa ou edite o exemplo.
Leia a tabela: cada variável aparece como só no servidor ou enviada ao navegador.
Resolva qualquer alerta, como um nome NEXT_PUBLIC_ que contém KEY, SECRET ou TOKEN.
Faça um novo build depois de alterar qualquer valor NEXT_PUBLIC_, porque o valor antigo fica gravado no bundle.
Mantenha os arquivos .env na raiz do projeto, mesmo quando o seu código fica em uma pasta src. O Next.js não os procura dentro de src.
Faça commit do .env e do .env.test com padrões seguros se a equipe quiser, mas nunca faça commit de arquivos .env*.local.
Leia variáveis públicas pelo nome literal completo. process.env[name] ou um process.env desestruturado não são substituídos no build.
Precisa de uma única imagem Docker para staging e produção? Leia as variáveis do servidor durante a renderização dinâmica e passe como props o que o navegador precisar.
Use loadEnvConfig do @next/env para carregar os mesmos arquivos em uma config de ORM, um script ou um setup de testes fora do Next.js.
Perguntas frequentes
Por que a minha variável de ambiente fica undefined no navegador?
Sem o prefixo NEXT_PUBLIC_, uma variável só existe no servidor, e o Next.js a substitui por uma string vazia no código do cliente. Adicione o prefixo só se o valor puder ser publicado, e depois faça o build de novo.
Mudei um valor NEXT_PUBLIC_ no meu host e nada aconteceu. Por quê?
Os valores públicos são embutidos quando o next build roda. Um bundle já publicado mantém o valor antigo até você fazer um novo build com o valor novo.
O .env.local funciona nos testes?
Não. Quando NODE_ENV é test, o Next.js ignora o .env.local para que toda execução de teste receba os mesmos valores. Coloque os padrões de teste no .env.test e os overrides pessoais no .env.test.local.
Uma variável pode fazer referência a outra?
Sim. Escreva $OTHER_NAME dentro de um valor e o Next.js o expande. Se o valor precisar de um cifrão literal, escape-o como \$.
Qual é o valor de NODE_ENV?
Se você não o definir, o next dev usa development e os outros comandos usam production. Os valores permitidos são production, development e test.
O que o NEXT_PUBLIC_ realmente faz
O prefixo é uma instrução para o bundler. Durante o next build, cada process.env.NEXT_PUBLIC_SOMETHING literal no seu código é substituído pelo valor do ambiente em que o build rodou, e esse texto acaba nos arquivos JavaScript que qualquer pessoa pode baixar.
Isso tem duas consequências. Primeiro, uma variável pública nunca é secreta, não importa o nome do arquivo. Segundo, ela fica congelada: promover um build de staging para produção leva junto o valor de staging.
Lendo valores em runtime
O código do servidor pode ler qualquer variável, pública ou não. Para garantir que um valor seja lido a cada requisição e não no build, renderize a página dinamicamente, por exemplo aguardando connection() de next/server antes de ler process.env.
O navegador não consegue ler variáveis do servidor de jeito nenhum. Se um Client Component precisa de um valor em runtime, busque-o em um Route Handler seu ou passe-o como prop a partir de um Server Component.
Proteja-se contra vazamentos
Um helper que lê uma chave de API pode ser importado por engano em um Client Component. Adicione import 'server-only' no topo desses arquivos e o build falha se um arquivo do cliente os importar.
Lendo variáveis no código
Valor só do servidor em um Route Handler
DB_URL não tem prefixo, então só existe no servidor. Route Handlers e Server Components podem lê-lo livremente.
Valor público em um Client Component
O nome literal completo é obrigatório. No build, o Next.js o troca pelo valor, então o navegador vê uma string simples.
Leia um valor a cada requisição
Aguardar connection() faz a página renderizar dinamicamente, então o valor vem do servidor em execução e não do build.
O loadEnvConfig aplica a mesma ordem de carregamento, o que mantém scripts e setups de teste alinhados com o app.
Verificador de .env
Cole as linhas do .env
Onde cada variável pode ser lida
Variável
Disponível em
Observação
Só no servidor
Servidor e navegador (embutida no build)
Não é uma linha de variável
O nome parece um segredo. Tudo com NEXT_PUBLIC_ fica visível para todo visitante.
Faz referência a {v}, que o Next.js expande.
NODE_ENV só aceita production, development ou test.