Como implantar Next.js na Vercel: variáveis de ambiente, domínio e monitoramento

Uma página de erro 500 da Vercel aberta no navegador. A variável de ambiente estava configurada no Vercel Dashboard, então por que a API ainda retornava undefined? Conferi o .env.local três vezes, fiz duas novas implantações e até limpei o cache do navegador — nada resolveu.

Meia hora depois, descobri que o problema estava no prefixo NEXT_PUBLIC_.

Talvez você já tenha passado por algo parecido: o projeto Next.js funciona perfeitamente no ambiente local, mas começa a apresentar problemas estranhos assim que é implantado na Vercel. Variáveis de ambiente não funcionam, o domínio próprio continua retornando 404 depois de horas de configuração ou um erro no certificado SSL provoca redirecionamentos sem fim.

O processo de implantação da Vercel é realmente simples, mas “simples” não significa “livre de armadilhas”. São justamente os detalhes de configuração que costumam consumir mais tempo. A seguir, você verá o processo completo para implantar Next.js na Vercel: da implantação com um clique à configuração correta das variáveis de ambiente, passando pelo domínio próprio e pelo monitoramento de desempenho. Os erros mais comuns estão destacados ao longo do caminho.

Implantação básica: publique em 5 minutos

A forma correta de implantar com um clique

O processo de implantação da Vercel é simples: envie o código ao GitHub, conecte o repositório à Vercel e clique algumas vezes. Mas há vários detalhes escondidos nessa aparente simplicidade.

O fluxo mais básico começa com o envio do projeto Next.js para um repositório Git — GitHub, GitLab ou Bitbucket. Depois, acesse vercel.com, entre com sua conta do GitHub e clique em “Import Project”.

A Vercel examina o repositório e, ao detectar um projeto Next.js, configura automaticamente o comando de build e o diretório de saída. Em geral, você não precisa alterar nada:

Build Command: next build
Output Directory: .next
Install Command: npm install

Clique em Deploy e aguarde um ou dois minutos. Você receberá uma URL no formato your-project.vercel.app. Nesse momento, a Vercel já terá distribuído os arquivos estáticos — JavaScript, CSS e imagens — pela Edge Network, com CDN global pronta para uso.

Mas há um detalhe que iniciantes costumam ignorar: confira o arquivo package.json.

Se o script build não executar next build, ou se next, react e react-dom não estiverem nas dependências, a implantação falhará. Já vi um projeto em que o script build executava webpack; nada funcionava porque a Vercel nem sequer reconhecia o Next.js.

Também existe o fluxo DPS — Develop, Preview, Ship. O nome parece sofisticado, mas o funcionamento é direto:

• Develop: desenvolvimento local com npm run dev
• Preview: ao criar um Pull Request ou enviar código para uma branch que não seja a principal, a Vercel gera automaticamente uma URL de pré-visualização para testes
• Ship: ao fazer merge na branch main, a Vercel implanta automaticamente em produção

Esse mecanismo é muito útil. Ao desenvolver um recurso novo e abrir um PR, por exemplo, a Vercel gera um endereço como your-project-git-feature-branch.vercel.app. Você pode enviá-lo diretamente à pessoa de produto ou à equipe de testes sem afetar o ambiente de produção.

Primeira tarefa após a implantação: conferir o log de build

Mesmo que a implantação tenha sido concluída, ainda não é hora de comemorar. Abra o Vercel Dashboard, entre no projeto, localize a aba “Deployments” e selecione a implantação mais recente.

O log detalhado de build mostra:

1. Quanto tempo levou a instalação das dependências: se passar de um minuto, o diretório node_modules pode estar grande demais ou a rede pode estar lenta
2. Se houve avisos durante o build: por exemplo, erros de tipo do TypeScript ou avisos das regras do ESLint
3. Quantas páginas estáticas foram geradas: o Next.js informa quais páginas usam SSG (Static Site Generation) e quais usam SSR (Server-Side Rendering)

Na primeira vez que implantei um projeto, o log mostrava vários erros de TypeScript, mas a implantação foi concluída mesmo assim. Depois descobri que a Vercel não bloqueava a implantação por causa desses erros — a menos que typescript.ignoreBuildErrors: false estivesse ativado em next.config.js.

Outro ponto fácil de esquecer: um build concluído não garante que a página funcione.

Já vi uma implantação terminar sem erros, mas a página retornar 500. A causa era uma rota de API que usava o módulo fs do Node.js para ler um arquivo local — as Edge Functions não oferecem esse tipo de acesso ao sistema de arquivos. As funções sem servidor (Serverless Functions) da Vercel são isoladas, e cada solicitação roda em seu próprio ambiente; não espere que arquivos persistam entre execuções.

Configuração das variáveis de ambiente: onde mais surgem problemas

Os três ambientes disponíveis

Agora chegamos ao ponto mais delicado. A configuração de variáveis de ambiente realmente pode confundir; foi aqui que fiquei preso por meia hora na primeira tentativa.

A Vercel divide as configurações em três ambientes: Production (produção), Preview (pré-visualização) e Development (desenvolvimento). Em resumo:

• Production: o ambiente oficial acessado pelos usuários, normalmente associado à branch main
• Preview: o ambiente de teste gerado automaticamente quando você abre um PR ou envia código para outra branch
• Development: o ambiente em que você executa npm run dev localmente

É possível definir valores diferentes em cada ambiente. A string de conexão do banco, por exemplo, pode apontar para o banco real em produção, para um banco de testes em Preview e para um banco local em Development.

Como configurar o desenvolvimento local?

Crie .env.local ou .env.development na raiz do projeto:

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here

O Git ignora o .env.local — confirme que ele está no .gitignore — para que a API key não seja enviada ao repositório.

Como configurar uma implantação na Vercel?

Abra o Vercel Dashboard → entre no projeto → Settings → Environment Variables.

Nessa tela, há três caixas de seleção: Production, Preview e Development. A variável fica disponível nos ambientes que você marcar.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Para configurar uma conexão com o banco usada somente em produção, por exemplo:

Name: DATABASE_URL
Value: postgresql://prod-server:5432/prod-db
Environment: ✅ Production

Salve e faça uma nova implantação para aplicar a variável.

Armadilha comum: configurar a variável e não implantar novamente.

A Vercel não inicia uma nova implantação automaticamente. Depois de alterar uma variável de ambiente, você precisa acionar uma implantação manualmente ou enviar outro commit para que o valor seja atualizado no ambiente de execução.

Variáveis do cliente e do servidor

Esta é a parte que mais confunde. Foi exatamente o erro em que caí às três da manhã.

No Next.js, as variáveis de ambiente são divididas em dois tipos:

1. Variáveis do servidor: acessíveis apenas pelo código do servidor, como rotas de API, getServerSideProps e getStaticProps
2. Variáveis do cliente: precisam do prefixo NEXT_PUBLIC_ e são incorporadas ao JavaScript enviado ao navegador

Veja um exemplo:

# Variáveis do servidor (seguras)
DATABASE_URL=postgresql://...
API_SECRET_KEY=abc123

# Variáveis do cliente (ficam expostas)
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
NEXT_PUBLIC_SITE_NAME=My Site

DATABASE_URL e API_SECRET_KEY só podem ser acessadas no servidor. O navegador não recebe esses valores. Já NEXT_PUBLIC_API_BASE_URL é incorporada diretamente aos arquivos JavaScript, e qualquer pessoa pode encontrá-la pelo console do navegador.

O erro que cometi foi este:

Eu tinha uma API key e precisava chamar um serviço de terceiros a partir do cliente. No início, não usei o prefixo NEXT_PUBLIC_, e o navegador sempre retornava undefined.

Depois de adicionar o prefixo, a API key funcionou — mas ficou exposta no código do navegador. Bastava abrir o DevTools e procurar por NEXT_PUBLIC_ para encontrá-la.

Qual é a abordagem correta?

Não chame a API de terceiros diretamente pelo cliente. Coloque a solicitação em uma rota de API do Next.js:

// app/api/data/route.ts (servidor)
export async function GET() {
  const res = await fetch('https://api.example.com', {
    headers: {
      'Authorization': `Bearer ${process.env.API_SECRET_KEY}` // Seguro
    }
  })
  return res.json()
}

// app/page.tsx (cliente)
const data = await fetch('/api/data') // Chama a própria API sem expor a chave

Assim, a API key permanece no servidor e nunca é exposta ao navegador.

Há ainda outro detalhe: as variáveis NEXT_PUBLIC_ são incorporadas durante o build, e não durante a execução. Portanto, depois de alterar um valor, é preciso executar um novo build para que a mudança entre em vigor.

Como sincronizar variáveis de ambiente

Em equipes, compartilhar variáveis de ambiente pode ser trabalhoso. O arquivo .env.local não deve ser enviado ao Git, mas quem acabou de clonar o projeto precisa saber quais variáveis configurar.

A Vercel oferece este comando:

vercel env pull .env.local

Ele baixa as variáveis de ambiente do tipo Development configuradas na Vercel e as salva no arquivo local .env.local.

Antes, instale o Vercel CLI:

npm i -g vercel
vercel link  # Vincula o projeto
vercel env pull

Observe que o comando baixa apenas as variáveis do ambiente Development. As variáveis de Production e Preview não são baixadas, por motivos de segurança.

Outra opção: usar .env.example como modelo.

Crie .env.example na raiz e liste todas as variáveis necessárias, sem preencher os valores:

# .env.example
DATABASE_URL=
API_KEY=
NEXT_PUBLIC_API_BASE_URL=

Envie esse arquivo ao Git. Depois de clonar o projeto, uma pessoa nova na equipe pode copiá-lo como .env.local e preencher os próprios valores.

O tamanho total das variáveis de ambiente na Vercel é limitado a 64 KB, e cada variável de uma Edge Function tem limite de 5 KB. A maioria dos projetos não chega perto disso, mas o limite pode ser atingido ao armazenar uma chave pública JWT ou uma imagem codificada em base64.

Configuração de domínio próprio

Vincule o domínio em três etapas

Um domínio como your-project.vercel.app pode parecer pouco profissional. Além disso, *.vercel.app está bloqueado na China continental. Se você precisa atender usuários nessa região, vincular um domínio próprio é indispensável.

Primeira etapa: adicionar o domínio à Vercel

Abra o Vercel Dashboard → entre no projeto → Settings → Domains.

Clique em “Add”, informe o domínio — por exemplo, example.com ou blog.example.com — e clique em Add.

A Vercel verificará o domínio e informará quais registros DNS devem ser configurados.

Segunda etapa: configurar o DNS

Há duas opções: registro A ou registro CNAME.

Para vincular o domínio raiz (example.com):

Type: A
Name: @
Value: 76.76.21.21

Para vincular um subdomínio (blog.example.com):

Type: CNAME
Name: blog
Value: cname.vercel-dns.com

Configuração específica para usuários na China:

Se a maior parte do seu público está na China, considere usar cname-china.vercel-dns.com no lugar de cname.vercel-dns.com. Esse é o endereço CNAME otimizado pela Vercel para a China continental.

Type: CNAME
Name: blog
Value: cname-china.vercel-dns.com

Outra opção é usar um registro A apontando para um IP mais adequado à região:

Type: A
Name: @
Value: 76.223.126.88 ou 76.76.21.98

Depois de configurar o DNS, aguarde de alguns minutos a algumas dezenas de minutos, dependendo do provedor. A Vercel detectará automaticamente quando os registros estiverem ativos.

Terceira etapa: validar

Volte ao Vercel Dashboard e atualize a página. Se o domínio exibir “Valid Configuration” em verde, a configuração foi concluída.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Abra o navegador e acesse o domínio. O projeto Next.js já deve estar disponível.

Armadilha comum: configuração incorreta do DNS.

Já vi alguém preencher o campo Name do CNAME com o domínio completo, como blog.example.com, em vez de apenas blog. O DNS não era resolvido e o domínio nunca ficava ativo.

Também é comum digitar o IP errado no registro A ou aguardar sem perceber que o cache do provedor DNS ainda não foi atualizado, o que mantém a resposta 404 por mais tempo.

Configuração automática do certificado SSL

A boa notícia é que a Vercel solicita automaticamente um certificado SSL da Let’s Encrypt. Nenhuma configuração adicional é necessária para ativar o HTTPS.

Quando o domínio entra em funcionamento, a Vercel inicia a emissão do certificado, que costuma levar alguns minutos. Na página Domains, o status aparece primeiro como “Certificate Status: Provisioning” e depois muda para “Active”.

Após a emissão, acesse https://example.com para confirmar que o cadeado aparece no navegador.

Há, porém, uma armadilha: certificado incompatível pode causar redirecionamentos sem fim.

Quando o domínio raiz (example.com) e o subdomínio www (www.example.com) estão configurados, a Vercel normalmente redireciona um deles para o outro.

Se o DNS estiver incorreto ou se o certificado SSL tiver sido emitido para apenas um dos domínios, o navegador poderá ficar alternando entre http://example.com e https://www.example.com.

Solução: adicione example.com e www.example.com à Vercel e confira se os registros DNS dos dois estão corretos.

Além disso, alguns provedores DNS exigem o modo de SSL/TLS “criptografia completa”. O modo “criptografia flexível” pode causar incompatibilidade do certificado.

Como verificar se o SSL está ativo?

Abra https://example.com, clique no cadeado da barra de endereços e consulte os detalhes do certificado. Se aparecer “Issued by: Let’s Encrypt”, a configuração foi concluída.

Também é possível conferir pela linha de comando:

curl -I https://example.com

Verifique se o código de status HTTP é 200 e se a resposta inclui o cabeçalho Strict-Transport-Security (HSTS).

Estratégias para subdomínios e vários domínios

Configuração conjunta do www e do domínio raiz

É comum configurar example.com e www.example.com e redirecionar um deles para o outro.

Na Vercel, basta adicionar os dois na página Domains. Em Settings, escolha o “Primary Domain”, e o outro será redirecionado automaticamente para ele.

Estratégia de domínios para sites multilíngues

Se o projeto Next.js oferece vários idiomas por meio de i18n, você pode atribuir um subdomínio a cada idioma:

• en.example.com → versão em inglês
• zh.example.com → versão em chinês
• ja.example.com → versão em japonês

Adicione os subdomínios separadamente em Settings → Domains e configure i18n no arquivo next.config.js:

module.exports = {
  i18n: {
    locales: ['en', 'zh', 'ja'],
    defaultLocale: 'en',
    domains: [
      { domain: 'en.example.com', defaultLocale: 'en' },
      { domain: 'zh.example.com', defaultLocale: 'zh' },
      { domain: 'ja.example.com', defaultLocale: 'ja' },
    ],
  },
}

Vincular um domínio próprio a uma branch de Preview

Para associar um domínio exclusivo ao ambiente de pré-visualização — por exemplo, à branch staging — adicione staging.example.com na página Domains e selecione staging em “Git Branch”.

Assim, sempre que você enviar código para a branch staging, a Vercel implantará automaticamente em staging.example.com, sem afetar a produção.

Monitoramento e otimização de desempenho

Vercel Analytics e Speed Insights

Depois de publicar o projeto, você provavelmente quer saber se as páginas carregam rápido, como está a experiência dos usuários e onde estão os gargalos de desempenho.

A Vercel oferece duas ferramentas gratuitas: Analytics, para analisar o comportamento dos usuários, e Speed Insights, para analisar o desempenho.

Integração rápida do Speed Insights

Se o projeto usa o App Router do Next.js, disponível no Next.js 13 ou posterior, a integração é simples:

npm install @vercel/speed-insights

Depois, adicione uma linha ao layout raiz:

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
      </body>
    </html>
  )
}

Depois da implantação, a aba “Speed Insights” no Vercel Dashboard começará a coletar dados.

Monitoramento dos Core Web Vitals

O Speed Insights acompanha automaticamente três métricas de desempenho definidas pelo Google:

1. FCP (First Contentful Paint): tempo até a primeira renderização de conteúdo. O valor ideal é inferior a 1,8 s
2. LCP (Largest Contentful Paint): tempo até a renderização do maior elemento de conteúdo. O valor ideal é inferior a 2,5 s
3. CLS (Cumulative Layout Shift): estabilidade visual da página. O valor ideal é inferior a 0,1

Esses dados vêm do navegador de usuários reais, por meio de Real User Monitoring, e não de um teste de laboratório. Você consegue comparar o desempenho por região, dispositivo e navegador.

Como usar o Speed Insights para melhorar o desempenho?

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Em um projeto anterior, o Speed Insights mostrava um LCP próximo de 4 s, muito acima dos 2,5 s recomendados.

Ao abrir os detalhes, encontrei a causa na imagem Hero da página inicial: um PNG de 2 MB, sem compactação e sem o componente <Image> do Next.js.

Convertemos a imagem para WebP e usamos next/image para processá-la automaticamente. O LCP caiu para 1,8 s e a pontuação do Speed Insights subiu de 60 para 95.

É aí que os dados de usuários reais fazem diferença. Uma pontuação alta no laboratório não substitui a experiência de quem realmente acessa o site.

Analytics para entender o comportamento dos usuários

O Vercel Analytics mostra:

• Quais páginas recebem mais visitas
• De onde vêm os usuários
• Como as visitas se distribuem por região
• Quais páginas têm uma taxa de rejeição alta

O recurso é gratuito para projetos pessoais, com até 100 mil visualizações por mês, mas exige pagamento em projetos comerciais.

Configurações avançadas

Comando de build personalizado

Se o projeto tem um processo de build específico, você pode personalizar o comando em Vercel Dashboard → Settings → Build & Development Settings.

Por exemplo, se você usa pnpm em vez de npm:

Build Command: pnpm build
Install Command: pnpm install

Ou, se precisa executar um script antes do build:

Build Command: npm run prebuild && npm run build

Edge Functions e Edge Middleware

A Vercel permite executar código em pontos de presença distribuídos pelo mundo por meio de Edge Functions, com menor latência que as Serverless Functions tradicionais.

Se o projeto Next.js usa Middleware, a Vercel o implanta automaticamente como Edge Middleware. Autenticação, redirecionamentos e testes A/B, por exemplo, podem acontecer na borda sem retornar ao servidor de origem.

// middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request) {
  if (!request.cookies.get('token')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

Configurar o tempo limite das Serverless Functions

No plano gratuito, o tempo limite padrão das Serverless Functions da Vercel é de 10 segundos. Rotas de API com tarefas demoradas — como chamar uma API de terceiros ou gerar um PDF — podem ultrapassar esse limite.

Nos planos pagos, o limite pode chegar a 60 segundos. Outra opção é mover o trabalho demorado para uma fila em segundo plano, como Inngest ou Trigger.dev, sem bloquear a solicitação HTTP.

Proteger implantações de Preview com senha

Se o ambiente de Preview não deve ficar aberto ao público, ative a proteção por senha em Settings → Deployment Protection.

Marque “Password Protection for Previews” e defina uma senha. Depois disso, será necessário informá-la para acessar qualquer URL de Preview.

Esse recurso é útil para proteger dados confidenciais ou funcionalidades ainda inacabadas.

Conclusão

Agora o processo completo de implantação de um projeto Next.js na Vercel deve estar mais claro.

Ele começa com a implantação básica, passa pelos três ambientes de variáveis, pela configuração de domínio próprio e certificado SSL e termina no monitoramento de desempenho e nas opções avançadas. São situações que aparecem em praticamente todo projeto real.

A configuração das variáveis pode parecer complicada, mas a regra central é simples: variáveis do servidor não recebem prefixo, variáveis do cliente usam NEXT_PUBLIC_ e uma API key nunca deve ser exposta no cliente. É um erro que você só precisa cometer uma vez.

A configuração do domínio também parece simples, mas pequenos detalhes do DNS podem causar problemas. Para usuários na China, use cname-china.vercel-dns.com ou endereços como 76.76.21.21, otimizados para a região; caso contrário, o site pode ficar inacessível.

Para monitoramento, o Speed Insights é especialmente útil. Os dados de usuários reais são mais confiáveis que testes de laboratório. Se o LCP passar de 2,5 segundos, comece verificando imagens, fontes e a renderização inicial — às vezes uma única mudança melhora a pontuação em 30 pontos.

Com isso, você já conhece o fluxo completo para implantar Next.js na Vercel. Abra o terminal, envie seu primeiro projeto ao GitHub, conecte-o à Vercel e acompanhe a implantação automática. Ver o primeiro endereço entrar no ar costuma compensar os dez minutos de leitura.

Se encontrar algum problema, deixe um comentário. Tentarei responder. Boa implantação!