Dez 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çaram os verdadeiros meses 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 multilingue, 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 meu próprio portal
• Âmbito: seis idiomas, 15.718 páginas pré-renderizadas e 8180 endereços no mapa do site (build de 20.10.2026), com malha hreflang completa
• Cronograma: início em dezembro de 2025 (a 2 de dezembro o site ainda funcionava em WordPress com WPML e WP Rocket, segundo a Wayback Machine; o repositório Astro foi criado a 21 de dezembro), semanas até um build funcional, primeira versão deste relatório após cinco meses, esta atualização após dez
• 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: regras 301 que esbarraram no limite de 100 KB do ficheiro _redirects; hoje 3619 delas estão num mapa nas Cloudflare Functions e 249 em _redirects
• Stack: Astro com Tailwind CSS, pipeline de imagens AVIF, HTML estático distribuído na periferia global
• Resultado: PageSpeed (laboratório, móvel, 20.10.2026) 94 para a página inicial polaca e 98 para a página do serviço Astro, sem PHP nem base de dados em produção, paridade total entre seis idiomas

#Quanto custa migrar de WordPress para Astro

1. A transposição é a parte barata. Templates e exportação de conteúdo demoraram semanas; ao fim de dez meses, a cauda longa da migração ainda exige correções.
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 mais de 15.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.

#Quanto tempo demora migrar de WordPress para Astro

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.

#Redirecionamentos 301 ao migrar de WordPress para Astro

Depois de o build funcionar, seguiu-se a 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 chegou rapidamente aos milhares de regras. Em outubro de 2026 o mapa nas Cloudflare Functions tem 3619 regras e o ficheiro _redirects 249.

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.

#Como manter o hreflang sincronizado em seis idiomas

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, desenvolvi scripts automatizados de validação de paridade executados antes de cada commit.

#Erro JavaScript heap out of memory no build do Astro

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 (em outubro de 2026 são 15.718) (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.

Reestruturei 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 uma heap definida explicitamente (--max-old-space-size, 16 GB no perfil de produção). A 20 de outubro de 2026, o passo astro build gerou 15.718 páginas em 5 minutos e 30 segundos, e o envio com o Wrangler demorou mais 338 segundos.
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.

#Como dividir o sitemap do Astro em vários ficheiros

Outro obstáculo significativo residiu na arquitetura dos mapas do site (sitemaps). A integração padrão @astrojs/sitemap não conhece as regras de indexação que mantenho em cada coleção (noindex, limites de extensão, páginas de cidades).

Desenvolvi um gerador próprio. Em outubro de 2026 produz esta estrutura:

• Um ficheiro principal sitemap-index.xml que lista 24 mapas, quatro por cada um dos seis idiomas.
• Cada idioma tem ficheiros próprios para as páginas de serviços (sitemap-pages.xml), o blogue, o portefólio e as páginas de cidades (sitemap-locations.xml), num total de 8180 endereços.
• 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.

#Verificações automáticas antes do deploy de um site Astro

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.

Até maio de 2026 construí 34 verificações de qualidade automatizadas (run-gates.mjs); em outubro de 2026, npm run gates lista mais de 120. Exemplos:

• Integridade de ligações internas (check:incoming-internal-links e check:service-navigation-parity): Confirma que cada serviço recebe ligações internas de entrada e que a navegação coincide em todos os idiomas.
• 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.

#Otimizar imagens e alojar fontes localmente no Astro

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. Estabeleci 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, o que evita desvios de layout (Cumulative Layout Shift).
3. Tipografia auto-alojada: Eliminei todos os pedidos externos ao Google Fonts. A fonte Geist é servida a partir do meu próprio domínio em ficheiros WOFF2 com o subconjunto latino (pacote @fontsource/geist), o que previne o bloqueio de renderização e cumpre o RGPD europeu.

#Como adicionar JavaScript a formulários num site estático em Astro

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 (o formulário de contacto, a pesquisa, calculadoras), acrescento um pequeno script apenas nessa página:

• O formulário de contacto é HTML simples com um script curto no componente, sem framework no navegador.
• A proteção contra spam é assegurada pelo Cloudflare Turnstile, sem desafios visuais.
• Os dados seguem para um endpoint nas Cloudflare Pages Functions (functions/api/enquiry.ts), que envia a mensagem através do Resend e, se o Resend falhar, através do Web3Forms. Não há servidor de aplicação para manter.

#Como adicionar pesquisa a um site estático em Astro

O WordPress dependia tradicionalmente de consultas SQL à tabela wp_posts para pesquisas. Numa arquitetura puramente estática, a pesquisa usa um índice gerado no build e corre no navegador:

• Cada idioma tem o seu próprio ficheiro JSON (/api/search/<idioma>.json). A divisão por idioma foi necessária porque um único ficheiro partilhado ultrapassava o limite de 25 MiB por ficheiro do Cloudflare Pages.
• A página de pesquisa descarrega o índice do seu idioma e pesquisa-o no navegador com a biblioteca Fuse.js. Cada ficheiro tem hoje entre 7,7 e 9,4 MB, por isso só o descarrega quem abre a página de pesquisa, e não todos os leitores.
• O servidor não faz qualquer trabalho na pesquisa, seja qual for o número de utilizadores. O custo é o tamanho do índice, que cresce com o blogue.

#Como medir Core Web Vitals depois de migrar de WordPress para Astro

No ecossistema WordPress, as métricas de desempenho sofrem frequentemente regressões silenciosas após a atualização de plugins. No Astro, acompanho o desempenho assim:

• Lighthouse no GitHub Actions: o workflow lighthouse.yml é executado manualmente ou através de uma etiqueta no pull request, quando mudam templates ou o layout. Não corre a cada commit, porque os minutos de Actions são limitados.
• Medição com PageSpeed Insights: a 20 de outubro de 2026, o resultado laboratorial em móvel foi 94 para /pl/ (LCP 2,7 s) e 98 para /en/astro-developer/ (LCP 2,3 s). A Google ainda não mostra dados de campo CrUX para estes endereços, por isso trata-se de uma medição laboratorial e não de uma avaliação das Core Web Vitals.
• 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.

#Checklist para migrar de WordPress para Astro

Com base nesta migração, sintetizo 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.

#Devo migrar de WordPress para um site estático depois do PHP2Shell?

A 21 de outubro de 2026 o projeto PHP publicou correções para o PHP2Shell, duas vulnerabilidades críticas no próprio PHP (CVE-2026-109618 e CVE-2026-109619). Segundo o php.net, está em risco qualquer instalação PHP que sirva pedidos web, e para a configuração de maior risco existe um exploit demonstrado que atua antes de correr qualquer código da aplicação (php.net). A Wiz Research acrescenta que até uma simples aplicação “Hello World” numa versão afetada do PHP pode ser vulnerável (Wiz). Um site gerado em ficheiros HTML e servido sem PHP fica fora desse aviso. Este site é um deles: nessa semana não havia aqui PHP para atualizar. O que fazer num site que ainda corre em PHP está no meu guia sobre o PHP2Shell.

Na mesma semana, no r/webdev, o autor de uma publicação técnica que passou de WordPress para Hugo no Cloudflare Pages descreveu assim o ganho em segurança:

Para mim, o maior ganho é deixar de ter um portal /wp-admin/ bem conhecido, exposto e constantemente sondado, e de ter de me preocupar com vulnerabilidades da stack por baixo.

(tradução própria, u/Select_From, r/webdev)

Noutra discussão, um programador escreveu que, depois do PHP2Shell, converteu 45 sites WordPress de clientes para Astro em 36 horas com um agente de IA. Uma das primeiras respostas perguntou pela parte que um build estático deixa em aberto:

Estás sempre a falar de ficheiros estáticos no README do GitHub, mas e os novos artigos? O que é que usas para os clientes poderem adicionar dados novos ou editar os que já existem?

(tradução própria, u/Lower_Rabbit_5412, r/webdev)

O autor respondeu que criou um CMS baseado em Git para os 2 ou 3 clientes que queriam editar o site. A superfície de ataque do PHP desaparece, e cada tarefa dinâmica que o WordPress resolvia num só sítio passa para outro lado, com o seu próprio responsável:

Uma resposta na discussão sobre Hugo pôs a ordem dos problemas tal como os encontrei:

O maior obstáculo costuma ser os permalinks, cada URL antigo precisa de um 301 ou perdes posições. Depois vêm as partes dinâmicas: comentários, pesquisa, formulários.

(tradução própria, u/ResidentPomegranate6, r/webdev)

A migração dos templates levou-me semanas, e os meses seguintes foram para redirecionamentos, hreflang e as verificações descritas acima. Migrar significa reconstruir o site.

Atualizações e manutenção regular são muitas vezes a melhor resposta. O PHP2Shell foi fechado por uma atualização do PHP, e uma migração que demora semanas não ajuda um servidor que hoje está por corrigir. Mantenha o WordPress, o WooCommerce, o Magento ou outra stack PHP, e mantenha-a atualizada, se a sua equipa editorial trabalha no painel todos os dias, se o seu negócio depende de plugins com lógica real (loja, reservas, assinaturas, cursos) ou se ninguém na equipa vai assumir um fluxo de trabalho em Git. Um build estático faz sentido quando o conteúdo muda raramente, poucas pessoas o editam e a parte dinâmica se resume a um formulário e a uma caixa de pesquisa. Um site em PHP precisa de manutenção WordPress regular, com atualizações do PHP; a reconstrução como site estático é trabalho para um desenvolvedor Astro.

Atualização de 24 de outubro de 2026, um caminho intermédio: ficar no WordPress ou reconstruir em Astro não são as duas únicas opções. Matt Cromwell descreveu a 14 de outubro de 2026 como reconstruiu o site da empresa dele sem uma instalação pública de WordPress. O WordPress corre apenas no computador dele, no WordPress Studio; um compilador transforma o sistema de design em theme.json e padrões de blocos reutilizáveis; o plugin Simply Static exporta o site para ficheiros estáticos; e o Cloudflare Pages serve-os. O editor de blocos mantém-se, e o site público deixa de ter PHP para corrigir. O trabalho extra está nos formulários: um plugin de formulários que envia por PHP não funciona em páginas exportadas, por isso ele escreveu um endpoint à parte que envia as inscrições na newsletter para o MailerLite através da API. Também avisa que um site estático tem limites próprios, que não vêm do plugin. A solução serve um site institucional editado num só computador. Uma loja, uma área de membros ou uma equipa que publica todos os dias continua a precisar de um servidor. Se a edição tiver de estar online e a parte pública tiver de funcionar sem PHP, isso já é uma configuração de CMS headless.

#Que resultados dá a migração para Astro após dez meses?

Ao fim de dez meses, o balanço da migração para Astro no Cloudflare Pages é favorável para o meu portal técnico:

1. Tempo de resposta do servidor (TTFB): Uma página servida a partir da cache periférica da Cloudflare responde a partir de Gdynia em cerca de 0,21 a 0,26 s, incluindo a ligação TLS (curl, 20.10.2026). Não tenho uma medição comparável da época do WordPress, por isso não indico uma melhoria percentual.
2. Superfície de ataque menor: Sem PHP, base SQL e wp-admin, desaparecem classes inteiras de ataques típicos do WordPress: injeção de SQL, execução de código através de um plugin vulnerável, ataques de força bruta ao login. Fica uma superfície menor para vigiar: os endpoints nas Cloudflare Functions (formulário, API) e os cabeçalhos de segurança.
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 sites de conteúdo que valorizam velocidade e alcance em vários idiomas, este trabalho compensa. Se pretende implementar esta arquitetura na sua organização, conheça o meu trabalho de desenvolvedor Astro, ou explore o meu serviço de migração de WordPress para Astro. Encontrará mais análises aprofundadas no blogue técnico da WPPoland.