Padrões de SEO para headless WordPress: as sete coisas que a maioria das migrações estraga

#Padrões de SEO para headless WordPress: as sete coisas que a maioria das migrações estraga

O headless WordPress vende-se pelos Core Web Vitals, pela reutilização de conteúdo e pela rapidez editorial. Se ninguém estiver atento, enterra pelo caminho sete sinais de SEO concretos. Já fizemos migrações destas em número suficiente para saber quais custam semanas de recuperação e quais se mantêm certas de forma mecânica.

Este artigo é a lista de verificação. Não substitui o pilar do serviço headless WordPress, onde está o argumento de arquitetura. É o que verificamos antes, durante e depois de cada migração, por esta ordem.

#Em resumo

• Preserve os URLs canónicos ao nível do URL completo, não apenas do slug.
• Preserve o hreflang no HTML, não só no sitemap.
• Renderize as meta tags e o JSON-LD no servidor, não no cliente.
• Migre o histórico de redirecionamentos antes de mudar os URLs, não depois.
• Mantenha um único sitemap como fonte de verdade, não dois.
• Esconda a origem WordPress do índice dos motores de pesquisa.
• Transporte o texto alternativo das imagens e os dados estruturados de imagem.

#Como manter os URLs canónicos numa migração headless

Um URL canónico é uma promessa. Cada link externo, cada entrada no índice do Google, cada partilha nas redes sociais conta com ele. Uma migração headless que corta discretamente um segmento do caminho, muda maiúsculas e minúsculas ou reordena os parâmetros de consulta acabou de quebrar todas essas promessas sem que ninguém dê por isso.

Duas regras. Primeiro, recolha o conjunto completo de URLs canónicos da instalação WordPress antiga antes de tocar no front-end. Exportamos cada artigo, página e página de taxonomia publicados com o URL que o Google tem indexado; essa é a fonte de verdade. Segundo, escreva o canónico na resposta HTML do front-end headless, e não numa alteração ao <head> feita no cliente. Os motores generativos e os motores de resposta analisam o HTML inicial; as meta tags alteradas no cliente não existem para eles.

Se tiver mesmo de mudar um URL, faça um redirecionamento 301 do antigo para o novo e mantenha-o durante pelo menos um ano.

#Tags hreflang no HTML do headless WordPress

Os sites WordPress multilingues usam WPML, Polylang ou uma solução própria para gerir as traduções. O mapeamento acaba correto na base de dados. O front-end headless tem depois de renderizar <link rel="alternate" hreflang="..."> para cada variante de idioma na resposta HTML.

O padrão que escapa à maioria das agências: o hreflang tem de ser autorreferencial. A página em inglês lista-se a si própria e todas as alternativas traduzidas. A página em polaco lista-se a si própria e todas as alternativas. As duas listas coincidem. O guia do Google sobre versões localizadas exige que cada versão linguística se liste a si própria e a todas as outras e, quando duas páginas não apontam uma para a outra, o Google ignora as etiquetas.

Tratamos a geração do hreflang como parte do build, e não como uma decisão em tempo de execução. O mapa de caminhos é calculado no build e convertido em hash, e qualquer desvio faz falhar o build.

#Renderização no servidor das meta tags e do JSON-LD

A regressão de SEO mais comum que vimos em migrações headless: meta tags e JSON-LD inseridos por JavaScript depois de a página carregar. O navegador vê-os. O Googlebot por vezes vê-os. Os motores generativos, os assistentes de voz e a maioria dos crawlers de LLM normalmente não.

Duas regras. Renderize as meta tags, o canónico, o Open Graph e cada bloco JSON-LD de Schema.org na resposta HTML inicial. Com Astro, é esse o comportamento predefinido. Com Next.js, significa renderizar no servidor (metadados do App Router, ou o caminho antigo com getServerSideProps) e não depender de novas execuções de next/head no cliente.

O mesmo se aplica às imagens: um elemento <img> com alt e src no HTML é indexável. Um <img> injetado depois de um efeito no cliente é invisível para a maioria dos crawlers e para os pipelines de dados de treino de IA.

#Reutilizar o JSON-LD do Yoast no headless WordPress

O WordPress com Yoast SEO ou Rank Math já produz bom JSON-LD de Article, Product e Organization. Numa migração headless, a tentação é reescrevê-lo do zero no front-end. Resista.

Leia o JSON-LD existente a partir da origem WordPress, através do endpoint REST ou GraphQL. Passe-o adiante. Acrescente apenas o que o front-end sabe legitimamente e o WordPress não (por exemplo, carimbos temporais do build para dateModified, se o seu fluxo editorial não mexer nas datas). Dois sistemas a gerar JSON-LD sobreposto é o caminho para os relatórios de resultados enriquecidos da Search Console começarem a falhar.

Nas nossas próprias páginas usamos os componentes da fase 0 em src/components/seo/: DirectAnswer, FAQ e Quote. Cada um emite o seu próprio JSON-LD mínimo, sem se sobrepor ao schema Article da página.

#Como migrar os redirecionamentos antes de mudar os URLs

A ordem importa. A lista de verificação pré-migração recolhe todos os redirecionamentos internos e externos, incluindo os silenciosos (/wp-content/... para /uploads/..., redirecionamentos por código de país, variantes AMP). O novo front-end publica esses redirecionamentos no dia zero, antes da passagem pública para os novos URLs.

No Cloudflare Pages, mantemos o ficheiro _redirects abaixo do limite da plataforma de 2000 regras. Um build que ultrapassasse o limite falha. Tudo o que precisar de mais de 2000 regras vai antes para um Worker com lógica de redirecionamento com parâmetros.

Quando o DNS público finalmente muda para o novo front-end, nenhum redirecionamento é novo em produção: cada regra foi testada no build durante semanas antes da mudança.

#Um único sitemap XML para headless WordPress

O WordPress 5.5 acrescentou um /wp-sitemap.xml predefinido. O Yoast SEO e o Rank Math acrescentam os seus. A framework de front-end headless também gera um sitemap. Três sitemaps no mesmo domínio é a receita para deixar a Search Console de cabeça perdida.

A regra: escolha um sitemap canónico e desative ou redirecione os restantes. Normalmente geramos o sitemap na framework de front-end, para que os URLs correspondam exatamente ao site público, e redirecionamos com 301 o sitemap da origem WordPress para o do front-end. A origem WordPress torna-se assim invisível para a pesquisa.

#Como aplicar noindex ao backend do headless WordPress

Uma migração headless deixa a origem WordPress a funcionar, normalmente num subdomínio ou num hostname privado. Continua a servir HTML renderizado, tem um sitemap funcional e responde a pedidos REST. Os motores de pesquisa que encontrem essa origem indexam-na como duplicado do site público, e o duplicado não será o que posiciona.

Três controlos. O robots.txt da origem bloqueia todos os caminhos exceto os endpoints REST e GraphQL. A origem envia X-Robots-Tag: noindex, nofollow nos cabeçalhos HTTP de cada resposta HTML. O sitemap da origem é removido ou devolve 410.

Se a sua origem estiver no mesmo domínio que o site público, sob um prefixo de caminho (por exemplo, /wp-admin/ ou /wp/), aplicam-se os mesmos controlos, limitados a esses caminhos.

#Como o Google processa o JavaScript de um front-end headless

Segundo os conceitos básicos de SEO para JavaScript do Google Search Central, o Google processa as aplicações web em JavaScript em três fases: rastreio, renderização e indexação. O Googlebot coloca na fila de renderização todas as páginas que respondem com o código 200, a menos que uma meta tag ou um cabeçalho robots indique que não devem ser indexadas. Uma página pode ficar alguns segundos nessa fila, mas a documentação avisa que pode demorar mais.

Para um front-end headless a consequência é prática. O que chega na resposta HTML inicial é processado na primeira passagem; o que depende de JavaScript espera pela renderização. O mesmo guia afirma que a renderização no servidor ou a pré-renderização continua a ser uma boa ideia, porque torna o site mais rápido para utilizadores e rastreadores e porque nem todos os bots conseguem executar JavaScript. Por isso tratamos o HTML inicial como o contrato SEO de cada rota: título, meta descrição, canonical, hreflang, ligações e JSON-LD têm de lá estar sem executar nada.

As imagens seguem a mesma lógica. O guia do Google sobre carregamento diferido indica o carregamento diferido integrado no navegador e a API IntersectionObserver como métodos compatíveis com a pesquisa, porque carregam o conteúdo quando está visível na área visível e não dependem de deslocar a página nem de clicar, coisa que a Pesquisa Google não faz. Também desaconselha o carregamento diferido de imagens que o utilizador vê de imediato. A verificação faz-se no HTML renderizado: o URL da imagem tem de estar no atributo src do elemento <img>, o que a ferramenta de inspeção de URL da Search Console mostra.

#Porque é que a renderização dinâmica não resolve o SEO do headless WordPress

Durante anos, a saída rápida para uma SPA ligada ao WordPress foi a renderização dinâmica: servir HTML pré-renderizado aos bots e a aplicação JavaScript aos utilizadores. O Google Search Central descreve-a hoje como uma solução provisória e não recomendada e recomenda, em alternativa, a renderização no servidor, a renderização estática ou a hidratação.

A mesma página esclarece que o Googlebot geralmente não considera cloaking a renderização dinâmica, mas que servir conteúdo completamente diferente a utilizadores e rastreadores pode ser considerado cloaking. Num projeto headless isso obriga a manter dois caminhos de renderização que têm de produzir o mesmo conteúdo, e ninguém dá por isso quando divergem. Um front-end que renderiza no servidor ou no build elimina essa duplicação: utilizadores, Googlebot e rastreadores sem JavaScript recebem o mesmo HTML.

#Códigos de estado HTTP e soft 404 num front-end headless

Quando o front-end pede à REST API do WordPress um slug que não existe, recebe uma coleção vazia, não um erro. Se com isso renderizar um modelo de “não encontrado” com o código 200, o Googlebot coloca-o na fila de renderização como qualquer página válida e o resultado é um soft 404. Com renderização no servidor, a correção é direta: uma resposta vazia significa que o front-end devolve um 404 real, ou um 410 quando o conteúdo foi retirado de propósito.

O mesmo acontece com rascunhos e artigos privados. Segundo a referência do endpoint de artigos, o parâmetro status da coleção tem o valor publish por omissão, por isso um artigo despublicado desaparece da resposta e a sua rota tem de responder com um código de erro, não com uma página vazia.

Para rotas resolvidas apenas no navegador, o guia do Google propõe duas estratégias: um redirecionamento em JavaScript para um URL em que o servidor responde com 404 (por exemplo /not-found), ou acrescentar com JavaScript <meta name="robots" content="noindex"> às páginas de erro.

#Canonical, noindex e ligações definidos com JavaScript

O mesmo guia do Google fixa três regras que os builds headless quebram com facilidade.

• Canonical. Se a canonical for definida com JavaScript, tem de ter sempre o mesmo valor que no HTML original; etiquetas rel="canonical" múltiplas ou contraditórias podem dar resultados inesperados. Em headless isto acontece quando o HTML do servidor traz a canonical da origem WordPress e um componente de cliente a reescreve com o URL do front-end.
• Noindex. Quando o Google encontra noindex, pode saltar a renderização e a execução de JavaScript. Um front-end que envia noindex no HTML inicial enquanto carrega os dados e o retira depois com JavaScript deixa a página fora do índice. Se quer a página indexada, o código original não pode conter noindex.
• Ligações. O Google só descobre ligações que sejam elementos <a> com atributo href, e o guia pede que não se usem fragmentos para carregar conteúdo diferente, mas sim a History API. Um menu que navega com handlers onClick ou com rotas do tipo #/artigo deixa por rastrear a estrutura interna que o WordPress tinha.

#Como obter o inventário de URLs a partir da REST API do WordPress

A primeira regra deste artigo é exportar todos os URLs publicados antes de mexer no front-end. A REST API faz isso sem plugins. Segundo o manual de paginação da REST API, os endpoints de coleção devolvem um número limitado de itens por pedido; per_page aceita um inteiro de 1 a 100 e page indica que página de resultados devolver. Cada resposta inclui o cabeçalho X-WP-Total, com o número total de registos, e X-WP-TotalPages, com o número total de páginas. Basta ler X-WP-TotalPages no primeiro pedido a /wp-json/wp/v2/posts?per_page=100 e percorrer as restantes páginas.

De cada artigo interessam dois campos da referência de artigos: link, o URL do artigo tal como o WordPress o publica, e modified_gmt, a data da última modificação em GMT. O primeiro é a lista com que se compara cada rota do novo front-end; o segundo alimenta o lastmod do sitemap. O argumento modified_after limita a resposta a artigos modificados depois de uma data ISO 8601, o que permite builds incrementais sem descarregar todo o conteúdo de cada vez. O mesmo padrão de paginação serve para /wp/v2/pages e para os endpoints de taxonomias.

#Resolução de URLs, pré-visualizações e cache com WPGraphQL

O WPGraphQL é um plugin gratuito e de código aberto que dá ao WordPress um esquema e uma API GraphQL extensíveis. A documentação mostra como consultar um artigo pelo seu URI, ou seja, o caminho do artigo, usado como identificador. Para o SEO isto importa porque a rota pública e o conteúdo vêm da mesma fonte: o front-end pede o nó pelo caminho que recebe e não precisa de uma tabela própria que traduza rotas em identificadores.

As pré-visualizações exigem mais cuidado. Segundo a documentação de pré-visualizações, o WPGraphQL pode devolver a versão não publicada de um artigo, mas o pedido tem de estar autenticado com um método que o WordPress reconheça. Se não estiver, o WPGraphQL devolve o nó publicado como se não tivesse sido pedida uma pré-visualização, sem erro. Uma rota de pré-visualização com a autenticação avariada mostra em silêncio o conteúdo publicado. Por isso as rotas de pré-visualização levam noindex, ficam fora do sitemap e não passam pela cache pública, e o campo isPreview serve para confirmar que a pré-visualização foi mesmo aplicada.

A cache decide quanto tempo demoram a chegar ao HTML as alterações de título, descrição ou canonical feitas no WordPress. A documentação de desempenho indica que o WPGraphQL suporta pedidos GET, que uma CDN ou um proxy podem guardar em cache, e que a extensão WPGraphQL Smart Cache marca as respostas com o cabeçalho X-GraphQL-Keys e emite um evento com as etiquetas afetadas quando o conteúdo muda, para que o alojamento limpe apenas esses documentos. Com essa invalidação, uma alteração editorial aos metadados SEO chega ao front-end sem esperar que a cache expire.

#Guias relacionados sobre SEO em headless WordPress

Este artigo apoia o pilar do serviço headless WordPress. Para o momento da decisão, veja Headless WordPress, Next.js vs Astro 2026. Para a questão mais ampla da visibilidade, incluindo citações em LLM, o guia de visibilidade em IA e LLM é a nossa descrição de referência do que entregamos em AEO e GEO sobre estas bases de SEO.