Resolução de Builds Falhados

Quando um build do Kapsule Orbit falha, a página de detalhes da implantação fornece o log completo, um resumo de falha categorizado e uma correção sugerida. Este guia o orienta na leitura dessa página, as falhas que o Kapsule Orbit reconhece por nome, as que não reconhece, e o que fazer quando um build é bem-sucedido, mas o site ainda está incorreto.

Leitura da Falha

1. Abra seu projeto no Kapsule Orbit.
2. Abra a aba Implantações.
3. Clique na implantação com status Falhado.
4. Leia o resumo da falha acima do log primeiro, depois o próprio log.

O Kapsule Orbit atribui a cada falha uma categoria: Memória insuficiente, Erro de compilação, Falha de teste, Erro de lint, Erro de instalação, Erro de rede, Tempo limite, ou Erro desconhecido. A categoria informa qual parte do pipeline você deve examinar antes de ler uma única linha do log.

Também há um botão Obter diagnóstico de IA. Ele lê as últimas 120 linhas do log junto com a estrutura detectada e a categoria de falha, e retorna uma explicação em linguagem clara.

Se o build nunca iniciou e está preso em Enfileirado, vá para a seção sobre builds enfileirados abaixo.

Falhas que o Kapsule Orbit Reconhece por Nome

Estas vêm com uma correção sugerida específica na página de implantação.

Falhas Comuns Por Fase

Falha na Instalação de Dependência

A fase de Instalação resultou em erro.

• Gerenciador de pacotes incorreto. O Kapsule Orbit escolhe npm, yarn ou pnpm a partir de seu arquivo de travamento. Se mais de um arquivo de travamento for feito commit, a escolha pode não ser a que você espera. Delete os que você não está usando, ou defina explicitamente Comando de instalação em Configurações.
• Registro privado. Se uma dependência vem de um registro privado, o token de autenticação deve estar disponível no momento do build como uma variável de ambiente, e seu .npmrc deve referenciá-lo.
• Incompatibilidade de versão do Node.js. Alguns pacotes requerem uma versão mínima do Node. Defina Versão do Node.js em Configurações para o número de versão principal: 18, 20 ou 22.
• Memória insuficiente em um monorepo grande. Use npm ci em vez de npm install, e considere um plano com uma máquina de build maior.

Falha do Comando de Build

A fase de Build resultou em erro.

• Erros TypeScript ou lint. O Kapsule Orbit executa seu comando de build exatamente como escrito. Se seu build falhar localmente, falhará aqui também.
• Variável de ambiente de tempo de build ausente. Uma variável lida durante o build deve existir antes de o build ser executado, não apenas em tempo de execução. Adicione-a na aba Variáveis de ambiente e reimplante. Uma variável de tempo de build adicionada após uma implantação não se aplica retroativamente a ela.
• Diretório raiz incorreto em um monorepo. Defina Diretório raiz em Configurações para o caminho do app, por exemplo apps/web.

Build Com Tempo Limite

Builds são abortados em 30 minutos de tempo de relógio em todos os planos. Se o seu consistentemente se aproxima disso:

• Verifique o log para um processo aguardando entrada. Um build que solicita entrada é um build que trava.
• Evite --legacy-peer-deps em uma árvore de dependência grande a menos que você precise dela.
• Certifique-se de que o cache de build está sendo usado. Os planos Liftoff e Apex incluem isso; a página de implantação mostra Cache hit ou Cold build.
• Mude para um plano com mais vCPU de build. Veja Limites do Plano do Kapsule Orbit.

O Build Nunca Inicia

Uma implantação presa em Enfileirado está aguardando um slot de build. A página de detalhes mostra sua posição na fila e quantos de seus slots de build simultâneos estão em uso, e inicia automaticamente o build quando um se libera. Launch e Liftoff permitem um build simultâneo; Apex permite três.

Você pode ver tudo em andamento em sua conta em Kapsule Orbit, depois Fila.

Se uma implantação fica enfileirada sem nada mais em execução, é mais provável que esteja bloqueada do que enfileirada. Verifique se há:

• Aguardando aprovação, se Exigir aprovação para produção está ativado
• Um bloqueio de implantação no projeto
• Um cronograma de congelamento de implantação bloqueando a hora ou dia atual
• Verificações necessárias de CI aguardando seu pipeline
• Exigir sucesso de staging antes de produção aguardando uma implantação de staging do mesmo commit

O Build Foi Ignorado Inteiramente

Se um push não produziu nenhuma implantação, foi provavelmente filtrado propositalmente:

• Caminhos ignorados: cada arquivo no push correspondeu a um padrão como *.md ou docs/**
• Padrões de ignorar ramo: o ramo correspondeu a algo como dependabot/*
• Diretório raiz: nada no push tocou o subdiretório do monorepo para este projeto
• Visualizações de ramo desativadas, e o push não foi para produção ou staging

Build Com Sucesso Mas o Site Está Incorreto

Um build verde e um site quebrado é quase sempre um problema de configuração em vez de um problema de código.

404 em cada página. O Diretório de saída está errado: o Kapsule Orbit publicou uma pasta que não é sua saída de build. Verifique o que seu build realmente escreve. Os valores comuns são dist, .next, out, build e .output.

404 apenas em rotas dinâmicas. O app precisa de um servidor em execução e está sendo servido como arquivos estáticos. Ative o Modo de servidor em Configurações em Tempo de execução. Isto é necessário para Next.js com SSR, Remix, Nuxt e qualquer outra coisa que não seja uma exportação estática.

Assets 404 após uma implantação, para usuários que já estavam no site. Eles carregaram a página antiga e estão solicitando URLs de bundle antigas que não existem mais. Ative a Proteção de distorção em Configurações, que mantém os artefatos do build anterior disponíveis por uma janela de retenção após uma nova implantação entrar em vigor.

Variável de ambiente é indefinida em tempo de execução. Confirme que o escopo da variável realmente cobre este ambiente, e que a implantação é posterior à alteração. A página de detalhes de implantação lista exatamente quais chaves foram injetadas em tempo de build e as compara com sua configuração atual.

As configurações de build específicas da estrutura estão em Configurando seu Comando de Build e Diretório de Saída.

Tentando Novamente

Na página de implantação falhada:

• Tentar build novamente re-executa o mesmo commit.
• Mais opções de repetição, depois Tentar novamente com cache limpo, deleta o cache de build primeiro.

Você também pode fazer com que o Kapsule Orbit tente novamente para você. Repetição automática de build em Configurações re-enfileira builds falhados causados por erros de infraestrutura, como falha de rede ou tempo limite, até três vezes. Ele deliberadamente não tenta novamente erros de código, portanto uma falha de compilação, lint ou teste nunca faz loop.

Evitar que um Build Ruim Chegue aos Usuários

Se uma implantação já entrou em vigor e quebrou algo, faça rollback em vez de tentar corrigir sob pressão. Rollback promove um artefato já compilado e leva segundos. Veja Revertendo uma Implantação.

Para parar mais implantações enquanto você investiga, clique em Bloquear implantações no projeto. As implantações disparadas por push são então ignoradas até que você desbloqueie, enquanto as implantações manuais ainda funcionam para que você possa enviar a correção.

Você também pode fazer com que o Kapsule Orbit faça isso automaticamente: Rollback automático em caso de falha restaura a última implantação íntegra quando uma implantação de produção falha, e um caminho de Verificação de integridade a restaura quando a nova implantação não responde com um 2xx dentro de 15 segundos.

Ainda Preso

Se o log simplesmente termina sem mensagem de erro, o processo de build foi provavelmente encerrado: memória insuficiente, ou a máquina de build foi recuperada. Tente novamente uma vez. Se falhar da mesma forma duas vezes, abra um ticket do KPanel ou envie um e-mail para support@kapsulehost.com e inclua a ID de implantação mostrada na página de detalhes.

Leitura Relacionada

• Exibindo Logs de Build
• Configurando seu Comando de Build e Diretório de Saída
• Revertendo uma Implantação