Doze meses a migrar de WordPress para Astro no Cloudflare Pages

A mudança de plataforma de WordPress para Astro devia representar o projeto por inteiro. Revelou-se, no entanto, um simples prólogo. Exportar o conteúdo, reconstruir os templates em componentes Astro com Tailwind CSS, conseguir que um site estático compilasse e fosse implementado no Cloudflare Pages demorou escassas semanas. Depois começou o verdadeiro ano de engenharia: redirecionamentos, grafos hreflang, paridade estrita entre seis idiomas e um build que ultrapassou a infraestrutura onde estava a ser compilado. Este é um relatório técnico sobre onde foram investidos os recursos.

A polémica incide sobre a visão redutora da mudança de plataforma como uma simples transposição de templates. “Mudar do WordPress para um site estático” soa a uma tarefa pontual. Para um portal de conteúdo multilingüe, significa antes assumir o controlo direto de três sistemas essenciais que o WordPress ocultava: a camada de encaminhamento, a orquestração do build e a integridade estrutural entre mercados linguísticos. Nenhum destes desafios é insuperável, mas todos exigem disciplina contínua.

[!NOTE] O caso num relance

• Projeto: wppoland.com migrado de WordPress para Astro no Cloudflare Pages, uma reconstrução interna do nosso próprio portal
• Âmbito: seis idiomas, mais de 14.000 páginas pré-renderizadas com slugs descritivos e malha hreflang completa
• Cronograma: semanas até um build estático funcional, cerca de doze meses até uma visibilidade de pesquisa estável e sem recaídas
• Build: ultrapassou o teto de 8 GB do runner do Cloudflare Pages, resolvido construindo localmente com uma heap de 16 GB e implementando o artefacto com Wrangler
• Redirecionamentos: milhares de regras 301 que esbarraram no limite de 100 KB do ficheiro _redirects e foram migradas para uma camada de Cloudflare Functions
• Stack: Astro com Tailwind CSS, pipeline de imagens AVIF, HTML estático distribuído na periferia global
• Resultado: TTFB global abaixo dos 40 ms, superfície de ataque dinâmica nula, rastreio previsível para crawlers de IA, paridade total entre seis idiomas

#Migração de WordPress para Astro, o custo real: TL;DR em 4 pontos

1. A transposição é a parte barata. Templates e exportação de conteúdo demoraram semanas; a migração necessitou de cerca de doze meses para consolidar o posicionamento orgânico sem perdas de tráfego.
2. A camada de redirecionamentos é a primeira grande surpresa. Milhares de URLs históricos exigem regras 301 precisas, e esse volume colidiu com um limite de 100 KB do Cloudflare Pages que descartava regras em silêncio.
3. A paridade entre seis idiomas é trabalho permanente, não uma meta isolada. O hreflang, os URLs canónicos e a estrutura de secções têm de permanecer sincronizados em todas as variantes linguísticas.
4. O build superou a capacidade do runner padrão da nuvem. O limite de 8 GB de RAM é insuficiente para compilar 14.000 páginas pré-renderizadas; a solução foi compilar localmente com 16 GB de heap e enviar o pacote via CLI.

#Glossário: build estático, prerender, hreflang, periferia

O relatório fundamenta-se nos seguintes conceitos de arquitetura:

• Build estático - o portal inteiro é convertido previamente em ficheiros HTML puros durante a compilação, em vez de ser processado a cada pedido do utilizador.
• Prerender - geração antecipada da árvore DOM de cada página em ficheiros físicos no momento do build. Em seis idiomas, o volume total multiplica-se pelo número de variantes.
• Cloudflare Pages - plataforma de alojamento que distribui ficheiros pré-compilados pela rede CDN global e executa lógica serverless através de Pages Functions.
• Wrangler - ferramenta de linha de comandos da Cloudflare, utilizada para enviar diretamente a pasta dist/ compilada, contornando limitações do runner remoto.
• Hreflang - atributos de cabeçalho HTML que informam os motores de busca sobre as páginas equivalentes em cada idioma.
• Redirecionamento 301 - instrução HTTP permanente que transfere a autoridade e o histórico de indexação de um URL antigo para o novo endereço.

#Semanas: a transposição que toda a gente orça

A fase visível da migração é a única habitualmente orçamentada, e a estimativa inicial costuma estar correta. O conteúdo é extraído da base MySQL do WordPress para ficheiros Markdown com frontmatter em YAML. Os ficheiros PHP e temas são reescritos em componentes Astro com Tailwind CSS. O build compila com sucesso e o site é publicado no Cloudflare Pages. Um portal de dimensão moderada atinge um build funcional em poucas semanas. Trata-se da etapa visualmente gratificante que convence as equipas de que o projeto está praticamente concluído.

Na realidade, o projeto encontra-se apenas no limiar dos seus maiores desafios técnicos. Um build funcional apenas comprova que os componentes Astro geram HTML válido sem erros de sintaxe. Não garante que milhares de URLs históricos continuem a reencaminhar tráfego, que os grafos hreflang permaneçam coerentes no índice da Google ou que o motor Node.js suporte a expansão futura da base de artigos.

#Meses: a camada de redirecionamentos que ninguém agendou

O primeiro trimestre após a publicação inicial foi absorvido pela engenharia de redirecionamentos. Cada URL que o WordPress gerou desde 2006 (arquivos cronológicos, categorias, etiquetas de autor, taxonomias de plugins e slugs legados) exigia um redirecionamento 301 rigoroso para a sua nova localização no Astro. A ausência deste mapeamento resultava num aumento abrupto de erros 404 na Google Search Console e na perda imediata de autoridade orgânica.

Num site unilingue, este processo resume-se a uma folha de cálculo. Num ecossistema que suporta seis idiomas com slugs traduzidos (endereços em português, espanhol, alemão, polaco e norueguês), a tabela ultrapassou as 18.000 regras individuais.

Foi então que surgiu uma limitação não documentada do Cloudflare Pages: o ficheiro _redirects possui um teto rígido de 100 KB. Acima dessa dimensão, o analisador da plataforma ignora as linhas excedentes sem emitir qualquer aviso durante a publicação. Consequentemente, as primeiras regras funcionavam, enquanto as restantes resultavam em erros 404. A solução definitiva consistiu em transferir a lógica de redirecionamento para um middleware em TypeScript (functions/redirect-map.ts), que executa pesquisas em memória com complexidade O(1) na camada periférica.

#Meses: seis idiomas que têm de concordar para sempre

Em arquiteturas WordPress clássicas, plugins como WPML ou Polylang mascaram as relações multilingues na base de dados. Numa arquitetura estática SSG, todas as ligações e dependências ficam patentes no código e nos ficheiros.

As seis versões linguísticas de cada publicação necessitam de se manter estritamente alinhadas:

• Estrutura uniforme de títulos H2 e H3 na mesma sequência argumentativa.
• Malha completa e bidirecional de ligações hreflang no cabeçalho HTML para todas as cinco variantes irmãs.
• URLs canónicos exatos que respeitam a estrutura de rotas de cada mercado.
• Coerência de taxonomia e categorização em todos os idiomas suportados.

Quando uma versão se desvia (por exemplo, ao adicionar uma subsecção ou alterar um slug isoladamente), os motores de busca começam a desconsiderar os sinais hreflang devido a assimetrias. Isto provoca canibalização de palavras-chave entre mercados. Para evitar este problema, desenvolvemos scripts automatizados de validação de paridade executados antes de cada commit.

#Topologia de memória em Node.js com 14.000 páginas pré-renderizadas

O Astro processa e compila páginas estáticas num único processo de trabalho. À medida que o repositório ultrapassou as 14.000 páginas (artigos técnicos, páginas de serviços, estudos de caso e diretórios regionais em 6 idiomas), o limite padrão de 4 GB de memória heap do motor V8 revelou-se insuficiente.

O runner padrão do Cloudflare Pages disponibiliza 8 GB de RAM. Durante a validação de esquemas TypeScript, processamento de árvores sintáticas MDX (AST) e otimização de estilos CSS, o processo sofria falhas fatais com a mensagem JavaScript heap out of memory.

Reestruturámos todo o pipeline de publicação:

1. Compilação local em processadores Apple Silicon: O build é executado localmente em chips da série M com alocação explícita de memória via NODE_OPTIONS='--max-old-space-size=12288'. A máquina compila 14.477 páginas HTML em menos de 3,5 minutos.
2. Limpeza de módulos de pré-renderização: O Astro gera a pasta dist/.prerender para artefactos de servidor. Determinados ficheiros individuais atingiam 43,9 MiB, excedendo o limite de 25 MiB por ficheiro do Cloudflare Pages. O script de deploy elimina automaticamente estes ficheiros internos antes do envio.
3. Upload direto com Wrangler: O diretório dist/ verificado é enviado diretamente para a rede periférica da Cloudflare, eliminando etapas frágeis na nuvem.

#Geração modular de sitemaps e grafo canónico

Outro obstáculo significativo residiu na arquitetura dos mapas do site (sitemaps). A integração padrão @astrojs/sitemap gerava um único ficheiro XML gigantesco para 14.000 URLs, desrespeitando regras específicas de não indexação.

Desenvolvemos um gerador modular que produz uma estrutura hierárquica de 32 ficheiros XML:

• Um ficheiro principal sitemap-index.xml que aponta para 6 índices linguísticos regionais (sitemap-pt-pt.xml, sitemap-en.xml, etc.).
• Cada índice regional divide-se em ficheiros temáticos: artigos de blogue, páginas de serviços, estudos de caso e localizações.
• Filtragem rigorosa que exclui todos os URLs com a diretiva noindex (assegurada pelo validador check:noindex-sitemaps).

Esta divisão permite que os motores de busca e crawlers de IA processem os mapas de forma faseada, sem interrupções por tempo limite.

#As ferramentas que reconstrói e que o WordPress dava de graça

Um custo frequentemente subestimado ao abandonar um CMS tradicional é a necessidade de reconstruir as verificações de qualidade que o WordPress e os seus plugins executavam em segundo plano. O WordPress impedia slugs duplicados, mantinha a integridade relacional em MySQL e sinalizava hiperligações quebradas. No paradigma estático, qualquer gralha no frontmatter chega diretamente a produção se não existirem testes automatizados.

Ao longo de doze meses, construímos um conjunto de 34 verificações de qualidade automatizadas (run-gates.mjs), executadas antes de cada publicação:

• Integridade de ligações internas (check:links e check:service-navigation-parity): Analisa todas as rotas em busca de erros 404 e assegura que cada serviço principal recebe pelo menos dois links internos de entrada.
• Conformidade de caracteres e diacríticos (check:diacritic-wordlist): Deteta anomalias de codificação e caracteres incorretos em todos os seis idiomas.
• Proteção de tabelas de preços (check:no-own-prices): Impede que valores horários ou estimativas comerciais não autorizadas surjam em artigos informativos fora das páginas de preços aprovadas.
• Validação de Content Security Policy (check:csp-inline): Calcula hashes criptográficos SHA-256 para todos os scripts inline no HTML final, impondo cabeçalhos CSP estritos sem unsafe-inline.
• Auditoria de retórica de IA (check:slop-rhetoric): Identifica e remove clichés de marketing, mantendo um tom estritamente técnico e factual.

#Pipelines de multimédia e tipografia local em conformidade com o RGPD

Em ambientes WordPress, o redimensionamento de imagens decorre durante o carregamento no painel através de GD ou ImageMagick. No Astro, a otimização de imagem integra diretamente o processo de build.

O processamento indiscriminado de milhares de imagens de alta resolução provocou inicialmente sobrecargas de memória na biblioteca Sharp. Estabelecemos uma separação metódica:

1. Recursos estáticos pré-comprimidos: Imagens de fundo e elementos decorativos são convertidos previamente para AVIF e WebP na pasta public/, sendo servidos diretamente pela CDN sem sobrecarga de compilação.
2. Dimensões determinísticas: Todas as imagens no corpo dos artigos incluem atributos explícitos de width e height, eliminando qualquer desvio visual de layout (Cumulative Layout Shift, CLS = 0.00).
3. Tipografia auto-alojada: Eliminámos todos os pedidos externos ao Google Fonts. As fontes estão alojadas localmente no formato WOFF2 com subsetting latino, prevenindo o bloqueio de renderização e garantindo total conformidade com o RGPD europeu.

#Arquitetura de ilhas (Astro Islands) para interatividade sem sobrecarga

A maior vantagem técnica do Astro reside no envio de zero JavaScript por defeito para o navegador (Zero-JS by default). Os leitores que consultam documentação técnica descarregam unicamente HTML e CSS sem dependências supérfluas.

Nos pontos em que a interatividade é indispensável (como formulários de contacto, filtros ou calculadoras), aplicamos o conceito de Astro Islands:

• O formulário de contacto é carregado como uma ilha isolada com client:visible, descarregando o JavaScript apenas quando o componente entra no campo de visão.
• Menus de filtragem utilizam client:idle para executar scripts em períodos de inatividade do navegador, mantendo a linha de execução principal desimpedida.
• Elementos de navegação responsiva utilizam client:media="(max-width: 768px)", evitando que utilizadores em computadores desktop descarreguem scripts de menu móvel.
• A proteção contra spam é assegurada pelo Cloudflare Turnstile invisível, sem necessidade de desafios visuais intrusivos.
• Os envios de formulário são processados de forma sem estado através de um endpoint na periferia ligado a webhooks transacionais (Resend), eliminando a manutenção de servidores dedicados.

#Pesquisa estática em WASM no cliente sem servidor de base de dados

O WordPress dependia tradicionalmente de consultas SQL à tabela wp_posts para pesquisas. Numa arquitetura puramente estática, a pesquisa de texto integral opera inteiramente no cliente:

• Durante o build, é compilado um índice léxico compacto e segmentado a partir do corpo dos artigos, excluindo menus e código padrão.
• O navegador descarrega apenas pequenos blocos do índice (15-30 KB) correspondentes aos termos digitados, apresentando resultados com pesquisa aproximada (fuzzy search) e destaque de termos em menos de 15 ms.
• Dicionários de palavras vazias (stop-words) em seis idiomas garantem elevada precisão de pesquisa com consumo mínimo de largura de banda.
• A carga no servidor permanece nula, mesmo perante picos de milhares de consultas concorrentes.

#Monitorização contínua de Core Web Vitals em CI/CD

No ecossistema WordPress, as métricas de desempenho sofrem frequentemente regressões silenciosas após a atualização de plugins. No Astro, os limites de desempenho são validados programaticamente no pipeline de deploy:

• Lighthouse CI: Cada versão é submetida a auditorias automáticas que exigem Largest Contentful Paint (LCP < 1.0s), Interaction to Next Paint (INP < 50ms) e Cumulative Layout Shift (CLS = 0.00).
• Testes de regressão visual: Testes Playwright automatizados verificam a integridade dos layouts em ecrãs móveis e desktop antes da integração de código.
• Purga imediata de cache periférica: No momento da publicação, o script aciona a API de Zona da Cloudflare (purge_cache: {"purge_everything": true}), garantindo que todos os nós globais servem de imediato o conteúdo atualizado sem aguardar pela expiração de s-maxage.
• Cache imutável para recursos com hash: Ficheiros CSS, JS e imagens AVIF são distribuídos com Cache-Control: public, max-age=31536000, immutable, enquanto os documentos HTML são geridos com max-age=0, must-revalidate e etiquetas de cache periférica.

#Lista de verificação técnica: 10 passos antes de desligar o WordPress

Com base em doze meses de dados de produção, sintetizamos os passos fundamentais a cumprir antes da alteração dos registos DNS:

1. Inventário exaustivo de rotas: Exportar todos os URLs históricos da base MySQL do WordPress (artigos, páginas, categorias, ficheiros de arquivo, feeds RSS e anexos).
2. Desenho do mapa de redirecionamentos: Estruturar um mapeamento 301 completo que contemple todas as variantes linguísticas de cada slug.
3. Implementação de Edge Functions: Alojar o motor de redirecionamentos numa Edge Function (Cloudflare Functions / Worker) para ultrapassar limitações de ficheiros estáticos.
4. Validação de malha hreflang: Confirmar a existência de ligações recíprocas perfeitas em todas as variantes de cada página do portal.
5. Auditoria de esquemas JSON-LD: Validar esquemas Article, FAQPage, HowTo e Organization de acordo com as especificações do schema.org.
6. Implementação de sitemaps modulares: Segmentar os mapas XML e aplicar filtros rigorosos que excluam páginas com marcação noindex.
7. Perfilagem de memória e build: Testar a compilação em ambientes restritos e calibrar a memória heap do motor V8.
8. Configuração de cabeçalhos de segurança: Ativar CSP, HSTS, X-Frame-Options e Permissions-Policy diretamente na CDN.
9. Auditoria de indexabilidade: Garantir que ambientes de staging, páginas técnicas e duplicações estão excluídos da indexação.
10. Testes de fumo pós-migração: Configurar testes automáticos de resposta HTTP e monitorizar a Search Console imediatamente após a propagação do DNS.

#O que a migração comprou de facto: resultados após 12 meses

Após doze meses de recolha contínua de métricas em ambiente de produção, o balanço da migração para Astro no Cloudflare Pages é amplamente favorável para o nosso portal técnico:

1. Tempo de resposta do servidor (TTFB): Redução de uma média de 650-1200 ms (sob carga de PHP e MySQL) para valores estáveis de 25-45 ms em qualquer nó periférico da Cloudflare a nível mundial.
2. Eliminação de superfícies de ataque: A remoção do interpretador PHP, da base SQL e do painel wp-admin eliminou integralmente os vetores de ataque habituais (injeções SQL, vulnerabilidades de plugins, ataques de força bruta).
3. Acessibilidade para motores de busca e crawlers de IA: HTML limpo e semântico, desprovido de sobrecarga de JavaScript, permite que motores de busca e crawlers de grandes modelos de linguagem (OpenAI, Anthropic, Perplexity) processem a documentação técnica instantaneamente, otimizando a presença em GEO/AEO.
4. Custos operacionais previsíveis: A distribuição de ficheiros estáticos a partir da periferia tem custos residuais quando comparada com a manutenção de clusters dedicados de bases de dados sob elevado tráfego.

A conclusão técnica transparente: a migração de WordPress para Astro não é uma mera renovação visual de frontend. Trata-se de um projeto estrutural de engenharia de software onde a conversão de templates é a etapa mais simples, residindo o verdadeiro valor na arquitetura de encaminhamento, nas verificações de qualidade automatizadas e no rigor multilingue. Para organizações que exigem velocidade de topo e ausência de manutenção de servidores, é um investimento com retorno consistente. Se pretende implementar esta arquitetura na sua organização, conheça o trabalho do nosso desenvolvedor Astro, ou explore o nosso serviço de migração de WordPress para Astro. Encontrará mais análises aprofundadas no blogue técnico da WPPoland.