O Pipeline de Build

Quando você clica em Build, um processo em segundo plano transforma o banco de dados no site estático e, somente quando tudo tem êxito, troca os novos arquivos para o lugar. Nada a montante jamais mostra metade de um build. A primeira coisa que um visitante vê é ou o site antigo ou o novo inteiro.

Como um build começa

Edições de conteúdo nunca reconstruem o site por si mesmas. Um build é disparado do dashboard de administração, da API, de um webhook ou da linha de comando. No disparo, o sistema reivindica o build para que apenas um rode por vez: apertar Build duas vezes não inicia um segundo. O segundo gatilho simplesmente informa que um build está em andamento. O lock é liberado quando o build termina (ou falha), o que acontecer primeiro.

Uma vez reivindicado, o builder roda em segundo plano com seu banco de dados e diretório de saída entregues a ele explicitamente. Dependendo de como foi iniciado, o build pode ser a execução incremental padrão, um rebuild completo forçado do zero, ou um que contorna os portões de segurança por aquele único build. Quando ele termina, seu webhook de build configurado pode ser notificado, para que sistemas externos fiquem sabendo do evento.

O que o builder produz

O builder produz o staging: um diretório separado output/.next, não o live. O staging permanece lado a lado com o diretório ao vivo até a troca. Essa separação significa que toda decisão sobre se um build é seguro acontece antes de qualquer conteúdo ao vivo ser tocado, e todas as decisões de staging são registradas em log com seu resultado. A saída ao vivo permanece intocada por qualquer coisa que escreva durante um build.

Builds incrementais e o que torna uma execução "completa"

Todo build começa em modo incremental, a menos que você não o solicite ou que o builder decida que um não é seguro. Antes de o staging ser tocado, ele percorre uma checklist de elegibilidade:

incremental foi solicitado;
existe um timestamp do último build, e ele não está no futuro;
o diretório de saída ao vivo existe e contém um index.html;
um build fingerprint do último build bem-sucedido está em registro e ainda corresponde às configurações atuais e aos templates do tema (um fingerprint sem correspondência significa uma "mudança global");

Se qualquer verificação falha, o build cai de forma limpa para um rebuild completo e registra o motivo. Quando a checklist passa, o staging é pré-montado como hardlinks do live. Os arquivos de conteúdo são pagos em disco apenas onde mudaram, e os arquivos inalterados vão junto de graça.

Um build então re-renderiza apenas o conteúdo dirty: itens atualizados desde o último build, itens cujo horário agendado de publicação ou despublicação foi cruzado desde o último build, e quaisquer páginas/posts que dependam de blocos ou stacks alterados. Todo o resto é pulado e reutilizado do render cache.

Velocidade de renderização

A renderização roda multi-worker por padrão, usando a contagem de CPUs da máquina (até 16), com um modo sequencial de worker único disponível. Qualquer build recebe um limite de tempo geral. E um orçamento de escrita de 2 GiB dividido entre os workers. De modo que um build mal-comportado nunca possa travar o pipeline ou encher o disco em pleno voo.

Indo ao ar: a troca de staging

Quando o build termina com sucesso (e o promotion guard não se recusa a publicá-lo), o staging é movido para o live:

O layout de produção padrão usa um symlink: a troca é um único rename atômico: zero downtime.
Com um layout de diretório: um rename em dois passos introduz no máximo um breve momento entre as movimentações, seguro no mesmo filesystem; o diretório anterior é retido para limpeza.
O primeiro build de todos renomeia o staging concluído para o live.

Uma troca que falha faz rollback em vez de publicar pela metade, nunca deixando um diretório ao vivo quebrado.

Quando as coisas dão errado em pleno voo

Qualquer condição fatal. Timeout, estouro do orçamento de escrita, erros de renderização, ou uma falha no momento da promoção. Descarta o staging e deixa a saída anterior servindo como está. A assinatura do manifest de um build acontece antes da promoção, e se a assinatura ou a promoção caem para trás, o manifest anterior é restaurado, de modo que uma assinatura fora de serviço nunca alegue conteúdo que não está no ar (este portão só pode ser relaxado em ambientes de teste).

O que cada build escreve em disco

Depois de cada passagem por idioma:

Saída que não mapeia mais para o conteúdo atual. Itens excluídos, despublicados ou fora da janela. É removida, de modo que URLs obsoletas desapareçam; quer o staging tenha sido hardlinkado do live ou renderizado do zero, o conjunto mantido de caminhos publicados governa o que permanece;
o sitemap, o feed RSS e a página 404 por idioma;
links internos quebrados e avisos de HTML/a11y, todos registrados.

O log de build captura tudo isso. Os últimos 100 builds incluindo sua saída completa e relatórios de validação. Mais o timestamp do último build, que mantém as execuções incrementais elegíveis até o próximo.