WordPressEscape

Início / Guia

Workbench

Migrando 528.854 páginas do WordPress para o Hugo: notas de engenharia

Estas são as notas de trabalho da migração do Unlimited Charters, nosso site-irmão interno, do WordPress para o Hugo em maio de 2026. O resumo do negócio está no estudo de caso; aqui está a parte para quem precisa executar o trabalho: o que deu errado com meio milhão de páginas, os comandos que nos causaram problemas e as verificações que agora executamos em todos os sites, grandes ou pequenos.

Leitura de 6 min 9 seções Feito para ranquear
Nesta página
  1. Contexto
  2. Inventário de templates antes do conteúdo
  3. Builds particionados e armadilhas do sistema de arquivos
  4. Correções de desempenho aplicadas como alteração de template mais processamento de todo o conteúdo
  5. Configurações do Cloudflare que fizeram diferença
  6. Detalhes de schema e SEO
  7. A captura de leads é a parte que você não pode perder
  8. O que faríamos diferente
  9. Fontes e leituras complementares
  10. Perguntas frequentes
Resposta rápida

Nessa escala, os problemas estão mais relacionados ao sistema de arquivos e aos processos do que ao Hugo: particionar o build, manter o conteúdo armazenado fora do ponto de montagem de conteúdo do Hugo, nunca executar dois processos de movimentação no mesmo diretório e tratar cada correção como uma alteração de template acompanhada de uma execução automatizada em todo o conjunto de páginas. Os maiores ganhos de desempenho vieram das dimensões das imagens, do CSS crítico síncrono, de uma imagem LCP não lazy, de um widget de orçamento adiado com espaço reservado e da desativação do Cloudflare Email Obfuscation.

01

Contexto

O Unlimited Charters pertence ao mesmo grupo que o WordPressEscape; esta foi nossa própria migração de teste, realizada com acesso completo ao servidor. O site tinha pouco mais de meio milhão de URLs, principalmente páginas de localização baseadas em templates, além de hubs, páginas da frota e um blog. O objetivo era gerar um build do Hugo servido como arquivos estáticos por trás do Cloudflare, preservando todos os caminhos existentes.

02

Inventário de templates antes do conteúdo

Começamos agrupando as URLs pelo template do WordPress que as renderizava, não pelo padrão da URL. Cada família recebeu uma decisão: ser reconstruída como um layout do Hugo ou receber, por enquanto, um snapshot estático da saída do WordPress. Reconstruir primeiro as famílias com mais tráfego e gerar snapshots das páginas fora do padrão manteve o projeto avançando sem ficar bloqueado pelo enorme volume de páginas personalizadas.

Uma armadilha que vale conhecer: no WordPress, o caminho da URL nem sempre é o slug post_name. Páginas-pai, regras personalizadas de reescrita e importações antigas geraram caminhos que não correspondiam ao slug, então o caminho precisou vir do crawl, não do banco de dados.

03

Builds particionados e armadilhas do sistema de arquivos

Renderizar todas as páginas em uma única execução era lento e tornava qualquer pequena alteração cara. Particionamos o processo: mover os arquivos-fonte que não seriam compilados para um diretório temporário, gerar um subconjunto, fazer o deploy e restaurar os arquivos. Quatro armadilhas nos fizeram perder tempo:

  1. O diretório temporário precisa ficar fora do ponto de montagem de conteúdo do Hugo. Se ele ficar em qualquer lugar dentro do diretório de conteúdo montado, o Hugo continuará percorrendo todos os arquivos e o particionamento não servirá para nada.
  2. rsync --exclude=index.html exclui todos os index.html em todos os níveis, não apenas o arquivo no nível superior. Ancore o padrão (--exclude=/index.html).
  3. Dois processos de movimentação simultâneos no mesmo diretório fazem com que ele seja aninhado. Dois processos de restauração executados ao mesmo tempo produziram cerca de 367.000 diretórios um nível abaixo do correto. A produção continuou funcionando porque servia o conteúdo já gerado; um único script de movimentação os nivelou. Um único processo deve ser responsável pelo diretório, com essa regra garantida por um lock.
  4. mv dir/* target/ falha nesse tamanho (a lista de argumentos fica longa demais). Use find ... -exec mv -t target {} +.
# renderiza algumas páginas sem reconstruir tudo
flock /tmp/uc-content.lock bash -c '
  mv content/migrated/* ../stash/            # armazena FORA do ponto de montagem de conteúdo
  for s in $(cat targets.txt); do mv ../stash/$s content/migrated/; done
  hugo --minify -d ../staged
  find ../stash -mindepth 1 -maxdepth 1 -exec mv -t content/migrated/ {} +
'
04

Correções de desempenho aplicadas como alteração de template mais processamento de todo o conteúdo

Cada correção teve duas partes: corrigir o template do Hugo para que os builds futuros ficassem certos e ajustar o HTML já gerado, evitando a necessidade de um rebuild completo para publicar a alteração. As que mais fizeram diferença:

  • Dimensões das imagens. Um template definia width="1600" height="700", enquanto o CSS usava uma proporção diferente. Corrigimos 527.815 páginas. A largura e a altura precisam corresponder à proporção renderizada; caso contrário, o navegador reserva um espaço incorreto (otimize o CLS).
  • Regras conflitantes de aspect-ratio no mesmo seletor, em duas folhas de estilo; consolidamos tudo em uma única regra.
  • CSS crítico no arquivo assíncrono. As regras para dispositivos móveis necessárias na primeira renderização estavam em uma folha de estilos adiada, causando uma reorganização tardia do layout. Movemos essas regras para a folha de estilos síncrona.
  • Hero carregado com lazy loading. O loading="lazy" na imagem acima da dobra atrasava o LCP; substituímos por fetchpriority="high" (otimize o LCP).
  • Imagens LCP grandes demais foram substituídas por versões menores, economizando de 50 a 440 KB por página.
  • Widget de orçamento é carregado na primeira interação (com um fallback por timeout), e seu contêiner reserva 480 px (560 px em dispositivos móveis). Antes, a montagem do widget deslocava a página, gerando um CLS de aproximadamente 0,54.
05

Configurações do Cloudflare que fizeram diferença

  • Email Obfuscation desativado. O decodificador percorre o DOM após o carregamento e reescreve os links de e-mail, o que aparecia como uma mudança de layout. Foi a fonte mais persistente de CLS que encontramos.
  • Rocket Loader desativado. Ele reordena os scripts e interferia no carregamento adiado.
  • Limpeza após o deploy. Os caches de borda mantinham HTML antigo; limpar o cache por caminho após cada deploy evitou a veiculação de páginas desatualizadas (documentação de limpeza de cache do Cloudflare).
  • Meça em produção, não em staging. O staging, sem as mesmas configurações do Cloudflare, produzia pontuações de laboratório diferentes das observadas em produção.
06

Detalhes de schema e SEO

  • O Search Console reportou erros de dados estruturados porque uma entidade Service continha aggregateRating e review. Removemos esses campos em vez de tentar validá-los; a marcação precisa refletir o conteúdo que os usuários conseguem ver (diretrizes de dados estruturados).
  • Inicialmente, as publicações do blog eram renderizadas com o template de localização e herdavam o tipo de schema incorreto. Agora, cada template declara sua própria entidade.
  • 35 caminhos inconsistentes da frota e de serviços receberam redirecionamentos permanentes para as páginas aninhadas corretas (redirecionamentos).
  • A mídia foi movida de /wp-content/uploads/ para /uploads/ com uma única regra 301; uma execução paralela de sed reescreveu 528.852 dos 528.854 arquivos em poucos minutos.
  • Removemos o Yoast depois que o Hugo passou a gerar o sitemap, o schema, as meta tags e o robots.txt.
find static-v5 -name '*.html' -print0 \
  | xargs -0 -P 8 -n 500 sed -i 's|/wp-content/uploads/|/uploads/|g'
07

A captura de leads é a parte que você não pode perder

O formulário de orçamento é a forma como o site gera receita, então recebeu suas próprias verificações: o ponto de montagem do widget precisa existir no HTML gerado de todas as páginas que o utilizavam, os nomes dos campos precisam corresponder ao que o endpoint de recebimento espera e um deploy que substitui um diretório não pode excluir a página de orçamento independente. Um corte que elimina silenciosamente a captura de leads pode parecer bem-sucedido em todas as métricas de SEO, enquanto a empresa perde oportunidades.

08

O que faríamos diferente

  1. Desativar o Email Obfuscation antes da primeira medição de CLS.
  2. Particionar o build desde o primeiro dia.
  3. Bloquear o diretório de conteúdo desde o primeiro dia.
  4. Documentar o padrão alteração de template mais processamento de todo o conteúdo antes da primeira correção, não depois da quinta.
  5. Incluir a verificação de dados de campo (CrUX) na checklist de lançamento, porque as pontuações de laboratório no staging não representam a produção.

A visão de negócio do mesmo projeto, incluindo o que mantivemos no WordPress, está no estudo de caso.

09

Fontes e leituras complementares

Perguntas frequentes

Esta é uma migração de cliente?

Não. O Unlimited Charters é um site-irmão interno pertencente ao mesmo grupo que o WordPressEscape. É o nosso próprio caso de teste.

O Hugo consegue lidar com meio milhão de páginas?

Sim, mas os rebuilds completos são lentos o suficiente para que builds particionados e um gerenciamento cuidadoso dos arquivos façam diferença. A maior parte dos nossos problemas estava relacionada ao sistema de arquivos e aos processos, não a bugs do Hugo.

O que causou a maior mudança de layout?

O widget de orçamento sendo montado sem espaço reservado (cerca de 0,54 de CLS nas páginas de hub) e o Cloudflare Email Obfuscation reescrevendo a página após o carregamento.

Essas lições se aplicam a sites pequenos?

Sim. As mesmas verificações (paridade de URLs, dimensões das imagens, CSS crítico, imagem hero não lazy e widgets adiados) se aplicam a um site com 40 páginas; elas apenas são executadas em minutos, em vez de horas.

Analise meu site grátis

Veja se o seu site se qualifica para o mesmo tratamento

A auditoria gratuita de 60 segundos mostra sua pontuação real no PageSpeed, a contagem exata de páginas, as lacunas de SEO e os recursos do WordPress que precisam ser substituídos. Depois, o WordPressEscape reconstrói seu site no Hugo, mantém todas as URLs e entrega o código-fonte desde o primeiro dia - da mesma forma que o UC foi reconstruído.

Analise meu site grátis
Continue lendo
Todos os guias33
Pesquisas relacionadasmigração do wordpress para o hugo528.854 páginas (teste interno)build particionado do hugocorreção de cls no cloudflarelimpeza de schemaparidade de urls