Sair da Vercel com Next.js: guia de migração

Você pode tirar uma aplicação Next.js da Vercel sem trocar de framework. O Next.js funciona em hospedagens compatíveis com Node.js. O trabalho é fazer os ajustes, os serviços conectados e as tarefas agendadas funcionarem no novo ambiente. Next.js Opções de implantação

A primeira mudança costuma ser mais simples se você mantiver a base de dados e o armazenamento, fizer a aplicação funcionar em uma nova URL e só depois mover o domínio. Assim, haverá menos coisas para investigar ao mesmo tempo.

Este guia segue esse processo. Você pode usá-lo com a hospedagem Node.js que escolher; os exemplos do Adios mostram uma forma de colocar as etapas em prática. Você precisará dos arquivos do projeto, de acesso aos ajustes da Vercel e de acesso ao DNS do domínio quando estiver pronto para mudar.

1. Faça uma lista curta dos serviços usados pela aplicação

Mantenha os serviços que já funcionam

Mover a aplicação não significa mover seus dados. Se sua base de dados aceita conexões da nova hospedagem, geralmente você pode mantê-la. Verifique se existe uma lista de IPs permitidos ou outras restrições de conexão.

Faça o mesmo com o armazenamento de arquivos, a autenticação, os pagamentos e o e-mail. Mantenha os serviços que funcionam bem se forem compatíveis com a nova configuração. Por exemplo, a Vercel documenta como acessar o Blob de fora da Vercel com um token de leitura e escrita. Autenticação do Vercel Blob

Salve uma versão funcional do código antes de começar. Nesta primeira migração, evite combinar a troca de hospedagem com uma atualização do framework ou uma reformulação da base de dados.

Confira os ajustes fornecidos atualmente pela Vercel

Abra os ajustes do projeto na Vercel e os arquivos do projeto package.json, next.config.*, e vercel.json, se existir. Preencha esta pequena lista:

O que encontrar	O que anotar
Ajustes de compilação	Versão de Node, gerenciador de pacotes, comando de compilação e pasta do projeto
Variáveis de ambiente	Nomes das variáveis e se pertencem a Production, Preview ou Development
Base de dados e armazenamento	Quais serviços você usa e se a nova hospedagem consegue se conectar
Login e pagamentos	URLs de retorno e de webhook que apontam para a aplicação atual
Tarefas cron	Qual URL cada tarefa chama, com que frequência e o que altera
Domínios	Qual domínio os visitantes usam e onde seu DNS é gerenciado

Uma URL de retorno é o endereço para o qual um serviço devolve o usuário após uma ação, como fazer login. Uma URL de webhook recebe uma notificação de outro serviço, como uma atualização de pagamento. Pode ser necessário alterar as duas URLs quando o endereço da aplicação mudar.

Procure também no código por @vercel/ e VERCEL_. Confira cada resultado: algumas integrações funcionam em outros lugares, enquanto outras dependem de um valor ou serviço fornecido pela Vercel. Uma nova hospedagem não recriará esses ajustes automaticamente.

Mantenha a implantação anterior disponível enquanto prepara e testa sua substituta.

2. Confira se a aplicação funciona em modo de produção

Compile e inicie a aplicação no seu computador

Comece com a versão de Node e o gerenciador de pacotes já usados no projeto. Estes exemplos usam npm e pressupõem que você tem no repositório um arquivo package-lock.json.

Confira se os scripts de package.json incluam estas entradas. Combine-as com os scripts existentes e mantenha as etapas de compilação necessárias à aplicação.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Em um terminal aberto na pasta da aplicação, execute:

npm ci --include=dev
npm run build
npm start

npm ci instala as versões salvas no arquivo de lock. npm run build prepara a aplicação para produção. npm start executa essa compilação. Se usar pnpm ou Yarn, utilize os comandos equivalentes do seu projeto. Configuração do Next.js como servidor Node

Abra o endereço local mostrado no terminal. Confira algumas páginas, incluindo uma que carregue dados. Se a compilação informar um ajuste ausente, adicione-o ao ambiente local e tente novamente. Use credenciais de teste em operações que enviam e-mails, cobram pagamentos ou alteram dados de clientes.

Este exemplo usa a configuração normal de next start. Se a aplicação já usar output: 'standalone', mantenha o comando de inicialização do servidor gerado e inclua os recursos do navegador. As instruções do Next.js para standalone explicam essa opção de empacotamento.

Opcional: descreva a configuração para o Adios

Na hospedagem escolhida, configure o comando de compilação, o de inicialização e a porta. A porta é o número em que a aplicação escuta; o ajuste da hospedagem deve corresponder ao da aplicação.

No Adios, crie adios.yaml ao lado de package.json. Este exemplo usa Node 24, uma instância em execução e a porta 3000:

name: my-nextjs-app
region: de
replicas: 1

build_cmd: npm ci --include=dev && npm run build
start_cmd: npm start -- --hostname 0.0.0.0 --port 3000

runtime:
  name: node@24
  port: 3000
  health_path: /api/health
  memory_mb: 1024

Escolha uma versão de Node suportada e compatível com sua aplicação, além de uma região disponível para sua equipe. O ajuste --hostname 0.0.0.0 permite que a hospedagem acesse a aplicação em execução. Termine de adicionar os ajustes da próxima seção antes de implantar. O Guia de início rápido da Adios explica esses campos.

O health_path é uma URL que a hospedagem consulta para verificar se a aplicação responde. Caso ainda não tenha uma, este exemplo básico de App Router deve ficar em app/api/health/route.js, ou src/app/api/health/route.js se você usar src/:

export function GET() {
  return Response.json({ status: 'ok' })
}

Confira se o middleware de autenticação permite acessar essa URL sem login. Essa verificação confirma que a aplicação responde; não prova que o login, os pagamentos ou a base de dados funcionam. Você testará esses itens separadamente.

3. Copie os ajustes e conecte os serviços

Coloque cada ajuste no lugar certo

Copie os ajustes necessários da Vercel para a configuração da nova hospedagem. Use valores apropriados ao ambiente de teste: uma implantação de teste deve usar chaves de pagamento de teste e dados adequados.

Um ajuste pode ser necessário em dois momentos:

Durante a compilação: enquanto npm run build prepara a aplicação.
Durante a execução: enquanto a aplicação compilada atende requisições.

Exemplo de ajuste	Onde normalmente fica
`NEXT_PUBLIC_SITE_URL`	Ajustes de compilação; o valor pode aparecer no navegador
`DATABASE_URL`	Ajustes privados do servidor; também de compilação se ela consultar a base de dados
Segredo de assinatura da autenticação	Ajustes privados do servidor, conforme as instruções da biblioteca de autenticação
Chave de API de pagamento ou e-mail	Ajustes privados do servidor
`CRON_SECRET`	Ajustes privados do servidor para o exemplo de tarefa agendada abaixo

Use os nomes reais das variáveis da aplicação. Um nome que começa com NEXT_PUBLIC_ indica uma informação que pode ser pública. Nunca use esse prefixo para uma senha ou chave de API privada.

O Next.js insere os valores NEXT_PUBLIC_* referenciados diretamente no código do navegador durante a compilação. Se alterar um deles, compile novamente. Alterar apenas um ajuste de execução não atualizará esse código do navegador. Next.js variáveis de ambiente

Opcional: adicione segredos do Adios e implante

No Adios, selecione a equipe responsável pela aplicação e crie os valores privados em Segredos. Depois, faça referência a eles em adios.yaml. Para uma aplicação que use estas duas variáveis, adicione:

env:
  DATABASE_URL: secret://DATABASE_URL
  CRON_SECRET: secret://CRON_SECRET

O texto secret://DATABASE_URL indica ao Adios que carregue o valor armazenado. Não é a senha da base de dados. Adicione apenas as variáveis usadas pela aplicação. Segredos e configuração do Adios

Para um ajuste público necessário durante a compilação, adicione um bloco build.env. Substitua este endereço de exemplo pelo que pretende usar:

build:
  env:
    NEXT_PUBLIC_SITE_URL: https://app.example.com

Se o servidor também lê esse ajuste durante a execução, inclua-o em env também. Se a compilação precisar de um valor privado, use uma referência a um segredo em build.env. Não coloque valores privados no arquivo. Referência do manifest Adios

Depois de instalar a CLI do Adios, faça login, liste suas equipes e selecione a mesma usada em Secrets:

adios login
adios teams
adios teams switch YOUR_TEAM_ID
adios up

Substitua YOUR_TEAM_ID pelo ID da sua equipe. Execute estes comandos na pasta que contém adios.yaml. adios up envia e compila a aplicação, inicia uma versão e aguarda as verificações de integridade. Abra a URL gerada quando terminar. Implantações no Adios

Em outra hospedagem, siga suas instruções de implantação e depois continue com as mesmas verificações de tarefas e aplicação.

4. Substitua o Vercel Cron por outro agendador

Mantenha a rota atual da tarefa

Pule esta seção se sua aplicação não usa tarefas agendadas.

Uma tarefa cron é um trabalho executado em um horário programado, como enviar um relatório ou excluir registros expirados. Com o Vercel Cron, o código fica na aplicação e a Vercel chama sua URL. Mover o código não agenda a tarefa na nova hospedagem.

Por exemplo, você pode ter isto em vercel.json:

{
  "crons": [
    { "path": "/api/cron/daily-report", "schedule": "0 8 * * *" }
  ]
}

Essa configuração solicita uma execução diária de /api/cron/daily-report às 08:00 UTC. Você pode manter a rota e fazer outro agendador chamá-la. Tarefas cron da Vercel

Mantenha a rota protegida. Se ela já verifica o valor da Vercel CRON_SECRET, copie esse ajuste privado para a nova aplicação. O novo agendador precisa enviar um cabeçalho Authorization contendo Bearer seguido do mesmo segredo. A rota deve rejeitar credenciais ausentes ou incorretas antes de executar qualquer trabalho. Proteger tarefas cron da Vercel

Opcional: execute a tarefa com um workflow do Adios

Um workflow do Adios pode chamar a rota existente e mostrar o resultado de cada execução. Você também pode usar outro agendador compatível com requisições HTTPS e cabeçalhos de autenticação.

Mantenha o código da tarefa e substitua seu gatilho. Escolha um intervalo ou um agendador de horário fixo conforme as necessidades da tarefa.

Comece com uma execução manual. Em Segredos da mesma equipe do Adios, crie CRON_AUTHORIZATION. Seu valor deve ser o cabeçalho completo, Bearer seguido do valor atual de CRON_SECRET. A aplicação usa CRON_SECRET para verificar a requisição; o workflow usa CRON_AUTHORIZATION para enviá-la.

Crie workflows/daily-report.yaml. Mantenha-o separado do arquivo raiz da aplicação, adios.yaml:

workflow_id: daily-report
title: Daily report
team_id: YOUR_TEAM_ID
enabled: true
version: "1"

steps:
  - step_id: call-report
    name: Run the existing report route
    kind: http
    timeout_seconds: 30
    command:
      method: GET
      url: https://your-app.example.com/api/cron/daily-report
      headers:
        Authorization: secret://CRON_AUTHORIZATION

Substitua o ID da equipe e a URL pelos seus. Para essa primeira execução, use uma implantação de teste conectada a dados de teste: uma execução manual também envia os e-mails ou altera os registros indicados pela rota. Mantenha o caminho exato da configuração cron atual. A referência ao segredo deve preencher todo o campo do cabeçalho: escrever Bearer secret://CRON_SECRET enviaria esse texto literalmente. Segredos de workflows do Adios

Implante o workflow:

adios workflow deploy ./workflows/daily-report.yaml

Abra Workflows, inicie uma execução manual e confira o estado e a saída da etapa. Confirme que o relatório foi gerado ou que a base de dados foi alterada. Verifique também se requisições sem autorização são recusadas. Aumente timeout_seconds apenas se a rota precisar e a hospedagem permitir requisições com essa duração. Criar e inspecionar uma execução de workflow

Em seguida, escolha o horário de que realmente precisa:

Necessidade	Como agendar
Repetir a cada 24 horas; o horário exato não importa	Adicione um gatilho por intervalo do Adios
Executar às 08:00 UTC ou em um horário local específico	Use um agendador de calendário para disparar o workflow por webhook ou chamar diretamente a rota protegida

Para a opção por intervalo, adicione este bloco no nível superior do arquivo do workflow:

triggers:
  - type: schedule
    interval: 24h

Um intervalo de 24 horas não equivale a uma execução agendada para as 08:00. O Adios ainda não interpreta expressões cron de calendário gerais, como 0 8 * * *. Um novo intervalo pode disparar na próxima verificação do agendador, e reiniciá-lo redefine o acompanhamento dos intervalos. Escolha essa opção apenas se esse comportamento atender à tarefa. Comportamento do agendamento no Adios

Não adicione o bloco de gatilho até que as verificações da próxima seção sejam aprovadas e você esteja pronto para mover a tarefa. Aponte o workflow para a nova aplicação de produção, desative o agendamento da Vercel e confira se ainda há uma execução em andamento. Depois, adicione o gatilho e implante novamente com o comando anterior. A Vercel oferece o controle Disable Cron Jobs para todo o projeto; se estiver movendo apenas uma tarefa, remova a configuração dela e faça uma nova implantação na Vercel. Gerenciar tarefas cron da Vercel

Torne as execuções repetidas seguras. Para um relatório diário, registre qual data já foi enviada e recuse duplicatas usando uma restrição na base de dados ou proteção equivalente contra requisições simultâneas. O agendador atual do Adios não aplica o campo concurrency, portanto esse ajuste não impedirá execuções simultâneas.

5. Teste a aplicação na nova URL

Percorra as ações habituais de um cliente

Mantenha o domínio principal na aplicação existente enquanto testa o novo endereço. Se usar um provedor de autenticação externo, registre a nova URL de retorno antes de tentar entrar. Use contas e modos de pagamento de teste quando disponíveis.

Teste	Resultado esperado
Abra a página inicial e uma página interna	As duas páginas carregam, incluindo estilos, imagens e scripts
Faça login, atualize a página e saia	A sessão se comporta como esperado
Crie ou atualize um registro de teste	A alteração é salva e continua aparecendo após atualizar
Envie e abra um arquivo	O arquivo funciona e os arquivos privados continuam privados
Abra a URL privada de outra conta	O acesso é recusado
Dispare um webhook de pagamento de teste, se utilizado	O estado de pagamento esperado muda uma única vez
Execute uma tarefa agendada manualmente	O resultado esperado aparece sem ações duplicadas

Um teste de webhook deve verificar o que mudou na aplicação, não apenas se o endpoint respondeu com sucesso. No Stripe, teste também entregas duplicadas: a documentação informa que eventos podem ser entregues mais de uma vez. Guia de webhooks do Stripe

Se as duas versões se conectam aos dados de produção, ambas podem alterá-los. Controle as atividades de teste e mantenha as tarefas destrutivas desativadas até estar pronto para a mudança.

Use os logs para corrigir as falhas

No Adios, estes comandos mostram os logs da compilação e da aplicação em execução:

adios logs --build
adios logs --runtime

Em outra hospedagem, abra a visualização equivalente de logs. Comece pelo primeiro erro relevante:

Sintoma	Primeira verificação
A compilação informa que falta uma variável	Ela está disponível durante a compilação?
A aplicação inicia, mas a hospedagem a considera indisponível	O comando de inicialização, a porta e a URL de integridade correspondem?
A conexão com o banco de dados falha	O ajuste de conexão está correto e a base de dados permite acesso dessa hospedagem?
O login redireciona para a URL antiga	Atualize a URL de retorno do provedor de autenticação e a URL da aplicação
O ajuste de URL pública ainda mostra o valor antigo	Compile novamente após alterar a variável pública de compilação
A tarefa retorna `401 Unauthorized`	Confira o segredo da aplicação e o cabeçalho completo de autorização do workflow

Teste os recursos especiais da aplicação pela nova URL pública. Em um chat com IA, confira se o texto chega aos poucos. Em páginas com cache, altere dados de teste e confira se os visitantes veem a mudança. Se executar várias instâncias, siga as orientações do Next.js sobre cache compartilhado e outros ajustes para múltiplos servidores. Hospedar Next.js por conta própria

6. Mova o domínio depois de validar as verificações

Adicione o domínio e depois atualize o DNS

O DNS informa aos navegadores onde encontrar seu domínio. Antes de alterá-lo, salve os registros atuais para poder restaurá-los se necessário.

Adicione seu domínio à nova hospedagem e siga as instruções de verificação, DNS e HTTPS. No Adios, consulte o guia de configuração de domínios. Use os registros fornecidos para sua aplicação; evite copiar endereços de outro exemplo.

Se usou uma URL temporária nos testes, atualize as URLs da aplicação e de retorno para o domínio definitivo. Recompile os valores públicos alterados. Confira também os destinos dos webhooks e a URL do workflow.

Após atualizar o DNS, abra o domínio e repita as verificações de login, leitura e escrita de teste, e imagem. Confirme que está vendo a versão prevista. Alguns visitantes ainda podem chegar à aplicação antiga enquanto os registros DNS em cache expiram; mantenha ambas as versões compatíveis com a base compartilhada durante a transição.

Mantenha uma forma de voltar à aplicação que funciona

Mantenha a implantação anterior disponível enquanto verifica a nova. Salve a revisão funcional do código e seus ajustes, junto aos registros DNS anteriores.

Se uma função essencial falhar, como o login ou a gravação de dados, você pode restaurar o roteamento anterior enquanto investiga, desde que a aplicação antiga ainda funcione com a base de dados atual. Uma mudança de DNS leva tempo para chegar a todos e não desfaz alterações na base nem e-mails já enviados.

Registre qual agendador está ativo. Voltar o site para a Vercel não significa necessariamente reativar suas tarefas cron. Tome essa decisão separadamente para que apenas o agendador previsto execute o trabalho.

7. Use uma lista final de verificação

Confirme que a aplicação está pronta para os visitantes

A compilação de produção termina com sucesso e a nova URL serve a versão prevista.
Os ajustes necessários estão disponíveis durante a compilação ou a execução, conforme apropriado.
Funcionam o login, as alterações de dados, as imagens e os uploads.
As páginas e os arquivos privados continuam protegidos.
As integrações de pagamento e e-mail passaram pelos testes correspondentes.
Cada tarefa agendada tem um substituto testado, com horários e autenticação adequados.
O agendador antigo está desativado antes de iniciar a nova programação.
O domínio funciona com HTTPS, incluindo as URLs de retorno e de webhook.
A versão anterior funcional e os registros DNS estão disponíveis caso seja necessário voltar atrás.

Confira a primeira execução realmente agendada

Após a mudança, confira os logs, um fluxo normal de cliente e a primeira tarefa agendada. Um teste manual prova que a tarefa consegue executar; a primeira execução agendada também verifica o gatilho.

Guarde a lista de serviços e os resultados dos testes junto ao projeto. Eles facilitarão a verificação da próxima implantação.

Para saber mais sobre como executar o servidor Node por conta própria, leia Executando Next.js como servidor Node sem Lambda. Se quiser usar o Adios, o Guia de implantação do Next.js explica a configuração da plataforma.