Deploy na Vercel falhou? Comece pelo primeiro erro de build

Quando um projeto funciona localmente, mas o deploy na Vercel falha, o primeiro erro do log de build importa mais do que a última linha.

Abra o projeto no painel da Vercel, acesse Deployments e selecione o deploy que falhou. Em Deployment Details, expanda Building. Uma linha final como exited with 1 informa apenas o resultado; volte até o primeiro Error. É essa mensagem que indica qual código ou configuração deve ser investigado.

Reproduza o build de produção localmente

A partir do diretório do projeto, execute:

npm run build

Se o mesmo erro aparecer, a falha provavelmente está no código, e não na configuração da Vercel. Um build de produção pode revelar erros de tipo ou sintaxe que passaram despercebidos no servidor de desenvolvimento. Corrija o primeiro erro, execute o build novamente e envie a alteração ao repositório.

Os valores do .env.local estão ausentes na Vercel

Como o .env.local normalmente fica fora do Git, a Vercel não recebe automaticamente as variáveis de ambiente locais. Adicione apenas os valores necessários para a implantação sob Settings > Environment Variables, e selecione os ambientes corretos.

Mudanças nas variáveis de ambiente não se aplicam retroativamente a uma implantação existente. Adicione ou atualize o valor, depois reimplante. Use o prefixo NEXT_PUBLIC_ apenas em valores que possam ser expostos com segurança no navegador. Eles são incorporados ao bundle do cliente durante o build; portanto, nunca aplique esse prefixo a um segredo de API ou token do servidor.

As versões locais do Node.js e as da Vercel são diferentes

Uma dependência pode funcionar em uma versão do Node.js e falhar em outra. A Vercel atualmente oferece suporte às versões 20.x, 22.x e 24.x; projetos novos usam a 24.x por padrão.

Execute node -v localmente, depois compare com Settings > Build and Deployment > Node.js Version. Uma versão principal declarada em package.json tem prioridade sobre a configuração no painel:

{"engines":{"node":"22.x"}}

Module not found pode ser causado por maiúsculas e minúsculas

O sistema de arquivos padrão do macOS é insensível a maiúsculas e minúsculas, enquanto o Vercel constrói em um sistema Linux sensível a maiúsculas e minúsculas. Se o arquivo for nomeado Button.tsx mas o código importar ./button, a importação pode funcionar localmente e falhar na implantação. Compare cada caractere no caminho do erro com o nome real do arquivo.

Se Cannot find module 'xxx' citar um pacote, examine o package.json. Um pacote presente apenas no seu node_modules local, mas ausente das dependências declaradas, não estará disponível na instalação limpa da Vercel. Execute npm install package-name e faça commit também do package-lock.json atualizado.

A aplicação está em um subdiretório do repositório

Se a aplicação estiver em um diretório como frontend/ mas o Vercel construir a partir da raiz do repositório, pode não encontrar package.json ou o Next.js. Quando o log contiver uma mensagem como No Next.js version detected, defina Settings > Build and Deployment > Root Directory para o diretório da aplicação. A alteração se aplica a implantações subsequentes.

A implantação foi bem-sucedida, mas uma solicitação retorna 504

FUNCTION_INVOCATION_TIMEOUT não é uma falha de build. É uma resposta 504 que indica que uma função ultrapassou o limite de execução. Com o Fluid compute, a duração padrão atual é de 300 segundos, que também é o máximo no plano Hobby.

Verifique Settings > Functions para confirmar se o Fluid compute está habilitado e se o tempo máximo não foi definido abaixo do padrão. Projetos antigos com o Fluid desativado podem ter limites padrão bem menores.

O tempo máximo padrão para os planos Pro e Enterprise é de 800 segundos. Em um arquivo de rota do Next.js App Router, você pode declarar:

export const maxDuration = 800;

Funções Node.js e Python podem usar uma extensão beta de 800 a 1.800 segundos. Rotas do Next.js App Router também podem definir export const maxDuration = 1800;; outros ambientes de execução ou frameworks podem exigir um vercel.json. Se uma carga de trabalho no plano Hobby precisar de mais de 300 segundos, aumentar o limite não resolverá: divida o processamento em tarefas assíncronas com Workflow, Queue ou uma arquitetura semelhante.

Um erro de configuração também pode interromper o deploy antes do início do build, sem deixar nenhum log em Building. Nesse caso, leia a própria mensagem do painel — por exemplo, um erro de validação do vercel.json. Ao pedir ajuda, inclua o primeiro Error, o package.json e a estrutura do repositório, para que seja possível comparar o ambiente local com o da Vercel.