SEO para Astro

TL;DR — Astro é uma ótima escolha para SEO. Por padrão, ele transforma suas páginas em arquivos HTML simples antes do carregamento, então, quando o Google (ou qualquer bot) chega, seu conteúdo já está ali — sem esperar o JavaScript executar. Também é muito rápido. O ponto importante: o Astro oferece HTML limpo, mas não adiciona automaticamente os títulos das páginas, o sitemap ou as tags canônicas. Você configura tudo isso por conta própria (é fácil).

O que significa “SEO para Astro”

Astro é um framework web para construir sites. Sua grande ideia é “menos JavaScript”. Enquanto frameworks como React ou Next.js muitas vezes montam a página no seu navegador usando JavaScript, o Astro transforma suas páginas em arquivos HTML simples no momento do build e envia quase nenhum JavaScript, a menos que alguma parte da página realmente precise dele. Evidence for this claim Astro prerenders pages as static HTML by default and only sends client JavaScript for explicitly hydrated components. Scope: Astro default static output and islands architecture. Confidence: high · Verified: 2026-07-14 Astro: Why Astro

Essa única diferença explica por que o Astro é tão amigável aos mecanismos de busca. Quando um mecanismo de busca rastreia uma página, ele quer ler seu conteúdo. Em um site pesado em JavaScript, às vezes o conteúdo ainda não está na página — o bot precisa executar o JavaScript primeiro, e isso pode atrasar. Com o Astro, o conteúdo já está no HTML no momento em que a página carrega. Não há nada a esperar.

Eu mantenho meu próprio site, patrickstox.com, no Astro — portanto, isso não é teoria para mim. É a stack sobre a qual eu realmente construo.

Por que o Astro é bom para SEO

• O conteúdo está no HTML imediatamente. Sem atraso de renderização, sem conteúdo ausente.
• É rápido. Sites Astro são leves e tendem a pontuar muito bem nas métricas de experiência da página do Google (Core Web Vitals).
• Cada página tem sua própria URL real. Sem um roteamento sofisticado de aplicativo de página única que possa confundir os rastreadores.
• O JavaScript carrega apenas onde é necessário. Uma galeria de fotos ou uma caixa de busca pode ser interativa sem desacelerar o restante da página.

O que o Astro NÃO faz por você

Isso confunde muita gente. “Astro é otimizado para SEO” só é verdade pela metade. O Astro oferece uma base limpa, mas não faz automaticamente o seguinte:

• Escrever os títulos e as meta descriptions das suas páginas.
• Gerar um sitemap (você adiciona um plugin oficial gratuito para isso). Evidence for this claim Astro's official sitemap integration generates sitemap files from statically generated routes. Scope: Astro @astrojs/sitemap integration. Confidence: high · Verified: 2026-07-14 Astro: Sitemap integration
• Adicionar tags canônicas (que informam ao Google qual é a versão “oficial” de uma página).
• Adicionar dados estruturados (o código que alimenta os resultados avançados).
• Criar um arquivo robots.txt.

Nada disso é difícil — apenas cabe a você configurar. Pense no Astro como uma ótima cozinha: os eletrodomésticos são excelentes, mas você ainda precisa cozinhar.

A checklist inicial simples

• Adicione um sitemap com o plugin oficial @astrojs/sitemap.
• Defina uma URL title, description e canonical em cada página (geralmente a partir de um arquivo de layout compartilhado).
• Use o componente integrado <Image /> do Astro para fotos — ele faz com que carreguem rápido e impede que a página fique pulando.
• Coloque um arquivo robots.txt na sua pasta public/.

Quer a versão aprofundada — Server Islands, View Transitions, renderização estática versus no servidor e os erros exatos a evitar? Mude para a aba Avançado. Para entender o panorama maior de como os mecanismos de busca lidam com JavaScript, veja JavaScript SEO.

TL;DR — O Astro é bem estruturado para SEO: páginas e endpoints são pré-renderizados em HTML estático por padrão, então não há uma onda da fila de renderização para esperar por esse conteúdo — mas isso é um padrão, não uma garantia universal, e o HTML estático/no servidor, por si só, não prova rastreabilidade, indexação, rankings ou Core Web Vitals das suas URLs em produção. A arquitetura de ilhas hidrata apenas os componentes que você marca com uma diretiva client:* — todo o restante envia HTML sem seu próprio JavaScript de hidratação, embora scripts da página, outras ilhas e aprimoramentos do roteador ainda possam adicionar JavaScript em outras partes da página. O Astro não gera automaticamente meta tags, canônicas, sitemaps ou dados estruturados — conecte tudo isso explicitamente, de preferência validado por Content Collections + Zod. Server Islands (que exigem um adapter) servem a casca estática com conteúdo de fallback no documento inicial e buscam o conteúdo adiado de forma independente depois — verifique o que cada rastreador realmente recupera, em vez de presumir. View Transitions usam history.pushState e são seguras para SEO; o Google rastreia as páginas MPA subjacentes normalmente. Eu mantenho patrickstox.com no Astro, e os recursos abaixo são os que realmente uso — validados contra o site publicado, não apenas no ambiente local.

Por que o Astro contorna totalmente o problema de renderização de JavaScript

A razão principal de SEO para JavaScript ser difícil é a segunda onda. O Google busca primeiro seu HTML bruto e depois coloca a página em uma fila para renderização posterior em um Chromium headless — e essa fila é o risco. A própria documentação do Google descreve assim: “Googlebot queues all pages with a 200 HTTP status code for rendering unless a robots meta tag tells Google not to index the page. The page may stay on this queue for a few seconds, but it can take longer than that.” (tradução) «O Googlebot coloca todas as páginas com código de status HTTP 200 em uma fila para renderização, a menos que uma meta tag robots diga ao Google para não indexar a página. A página pode permanecer nessa fila por alguns segundos, mas isso pode demorar mais.» Em uma SPA renderizada no cliente, seu conteúdo não existe até essa onda de renderização acontecer.

O modo de saída padrão do Astro é estático: páginas e endpoints são pré-renderizados em um arquivo HTML completo no momento do build. Assim, para uma rota que usa esse padrão, o HTML bruto é a página renderizada. Evidence for this claim Astro uses static output and prerenders routes at build time by default. Scope: Astro default output mode; routes can opt out of prerendering. Confidence: high · Verified: 2026-07-14 Astro: On-demand rendering Não há uma segunda onda para esperar nessa rota, porque não resta nada para executar. O Googlebot vê todo o conteúdo na primeira busca. Como diz Joost de Valk (fundador do Yoast): “From an SEO perspective, static HTML on a CDN is a better starting point than most CMSes will ever give you.” (tradução) «Do ponto de vista de SEO, HTML estático em uma CDN é um ponto de partida melhor do que a maioria dos CMSs jamais oferecerá.»

Esse é o padrão, porém — não uma propriedade universal de todas as rotas. Defina output: 'server' e o padrão muda para a renderização sob demanda (mais sobre isso abaixo); mesmo em um projeto com padrão estático, um adapter permite que uma rota individual opte por sair dele com export const prerender = false. Nada disso é garantido apenas pela arquitetura: HTML estático ou no servidor, ilhas e adapters não garantem, por si só, rastreabilidade, indexação, rankings ou Core Web Vitals — isso depende da rota publicada e do rastreador específico, portanto verifique em vez de presumir que o framework resolve tudo.

Isso também ajuda com rastreadores que não conseguem renderizar. O Google observa claramente que “not all bots can run JavaScript” (tradução) «nem todos os bots conseguem executar JavaScript» — e essa é a realidade de 2026 para a maioria dos rastreadores de IA e muitas ferramentas de terceiros. A saída HTML-first do Astro é legível por todos eles onde realmente é pré-renderizada, não apenas pelo Googlebot. (Esse é o mesmo ponto que faço em SEO para um CMS headless: o modo de renderização é o produto.)

Arquitetura de ilhas: JS apenas onde você pede

O Astro renderiza seus componentes em HTML e, nas palavras dele, envia “just HTML & CSS, stripping out all client-side JavaScript automatically.” (tradução) «apenas HTML e CSS, removendo automaticamente todo o JavaScript do lado do cliente.» A interatividade é opcional. Você marca um componente com uma diretiva client:* — client:load, client:idle ou client:visible — e apenas aquela ilha é hidratada com JavaScript. Todo o restante continua sendo HTML estático. Evidence for this claim Astro client directives selectively hydrate interactive islands while other components remain static HTML. Scope: Astro islands and client directives. Confidence: high · Verified: 2026-07-14 Astro: Islands

Para SEO, isso chega perto do ideal. O conteúdo que o Googlebot precisa indexar é HTML simples, e seus widgets interativos não o prejudicam. client:visible é especialmente útil: um componente abaixo da dobra nem começa a hidratar até entrar na área visível, então nunca bloqueia seu LCP. O conceito vem de Jason Miller (criador do Preact), que descreveu “rendering HTML pages on the server, and inject[ing] placeholders or slots around highly dynamic regions” (tradução) «renderizar páginas HTML no servidor e injetar placeholders ou slots ao redor de regiões altamente dinâmicas» para a hidratação seletiva.

Duas nuances merecem precisão, porque a cobertura dos concorrentes tende a misturá-las:

• client:only é outra coisa. Diferentemente de client:load/client:idle/client:visible, um componente client:only ignora completamente a renderização no servidor — ele não produz HTML no servidor. Qualquer conteúdo indexável colocado apenas dentro de um componente client:only não está no documento que o Googlebot busca; só existe depois que o navegador o hidrata. Não coloque ali o conteúdo principal.
• Isso é hidratação seletiva, não resumability. O Astro executa novamente o código do cliente de cada ilha do zero no navegador; ele não retoma o estado de execução serializado no servidor como faz um modelo de resumability (como o do Qwik, por exemplo). Os dois conceitos são confundidos em textos — não são o mesmo mecanismo.

E um componente não hidratado não representa todo o cenário de JavaScript da página. “Zero JS” descreve um componente sem uma diretiva client:* — o Astro ainda pode enviar tags <script> no nível da página, o roteador de View Transitions e outras ilhas em outras partes da mesma página. Descreva o que é enviado por componente/rota, não como uma afirmação geral sobre a página.

O que o Astro NÃO faz automaticamente

O Astro gera HTML semântico limpo — e nada mais, do ponto de vista de SEO. Não há metadados, canonical, sitemap ou dados estruturados prontos. O mito de que “o Astro é automaticamente otimizado para SEO” é exatamente isso: um mito. Você é responsável por:

• Meta tags (title, description, Open Graph, Twitter)
• URLs canônicas
• O sitemap (por meio da integração oficial)
• Dados estruturados / JSON-LD
• robots.txt

O Astro é a melhor fundação que já usei, mas é uma fundação, não uma casa pronta.

O sitemap: @astrojs/sitemap

Instale-o com npx astro add sitemap. Ele rastreia suas rotas geradas estaticamente e emite um sitemap-index.xml mais arquivos sitemap-0.xml divididos em partes durante o build. Duas coisas costumam pegar as pessoas: Evidence for this claim Astro's official sitemap integration generates sitemap files from statically generated routes. Scope: Astro @astrojs/sitemap integration. Confidence: high · Verified: 2026-07-14 Astro: Sitemap integration

• Você precisa definir site: em astro.config.mjs. Sem isso, a integração não gera nada silenciosamente. Essa é a causa mais comum de “onde está meu sitemap?”.
• Você precisa adicionar a linha do sitemap a robots.txt por conta própria. O Astro não faz isso.

Para ter controle, filter() exclui rotas (páginas de preview/draft — exatamente para isso que uso aqui), serialize() permite definir lastmod/changefreq/priority, e a opção i18n emite entradas hreflang no sitemap. É isso que a documentação atual de @astrojs/sitemap especifica — confirme na versão instalada se você estiver em uma versão mais antiga, pois o comportamento da integração já mudou entre versões principais.

O escopo que confunde as pessoas: a descoberta da integração tem como alvo rotas geradas estaticamente. Se alguma das suas URLs só existe em tempo de execução — rotas renderizadas no servidor (output: 'server') ou rotas geradas sob demanda, e não no build — não presuma que estejam no sitemap. Adicione-as explicitamente com customPages e depois abra de fato o sitemap-index.xml após um build para confirmar que estão lá. Não aceite que “a integração resolve isso” sem verificar algo que não seja uma rota estática de build.

Meta tags e canônicas: o padrão BaseLayout

O Astro não tem um componente especial <Head> — você controla <head> diretamente nos arquivos .astro. O padrão comum (e o que eu faço) é um único BaseLayout.astro que recebe title, description e canonicalURL como props e escreve o head. Defina a canonical explicitamente em cada página e mantenha-a consistente com og:url. Você não precisa de uma biblioteca, mas o pacote comunitário astro-seo (npm) é um wrapper conveniente de um componente para title/description/OG/Twitter/canonical, se quiser.

Content Collections como rede de segurança para SEO

Este é um recurso de SEO subestimado do Astro. Content Collections são uma camada de conteúdo com tipagem segura para Markdown/MDX/JSON, com validação de schema Zod. Isso permite tornar title e description campos obrigatórios — e, se uma página não tiver um deles, o build falha. Você não consegue publicar acidentalmente uma página sem título. As funções de consulta (getCollection(), getEntry()) geram páginas estáticas no build, então a saída é HTML simples quando publicada. E, como o MDX mantém o Markdown bruto como fonte de verdade, esses arquivos também são conteúdo-fonte limpo para rastreadores de IA e padrões no estilo do llms.txt. Este mesmo site é construído com Content Collections e frontmatter validado por Zod.

astro:assets: imagens feitas corretamente (com uma armadilha)

O componente <Image /> converte automaticamente para WebP, infere dimensões para “avoid Cumulative Layout Shift (CLS),” (tradução) «evitar Cumulative Layout Shift (CLS)», define loading="lazy" por padrão e exige alt — a ausência de alt é um erro de compilação. <Picture /> amplia isso com elementos <source> de fallback AVIF/WebP.

A armadilha: o loading="lazy" automático é errado para sua imagem LCP (geralmente o hero). Carregar a imagem mais importante de forma lazy atrasa seu carregamento. Para imagens acima da dobra, substitua por loading="eager" e fetchpriority="high". Imagens remotas precisam de width e height explícitos.

Server Islands: o que os rastreadores realmente veem

Server Islands (Astro 4.12+) são o recurso que a maioria dos guias concorrentes entende errado. Com server:defer, um componente é renderizado no servidor independentemente da página principal. A casca estática é servida imediatamente; conforme a documentação do Astro, “Your page will be rendered immediately with any specified fallback content as a placeholder. Then, the component’s own contents are fetched on the client and displayed when available.” (tradução) «Sua página será renderizada imediatamente com qualquer conteúdo de fallback especificado como placeholder. Depois, o próprio conteúdo do componente será buscado no cliente e exibido quando estiver disponível.»

Duas coisas precisam ser exatas. Primeiro, Server Islands exigem um adapter — são um recurso sob demanda, não algo que um build puramente estático produz sozinho. Segundo, a sequência é: o documento inicial envia o conteúdo de fallback que você configurou, e o conteúdo real da ilha é uma solicitação separada e independente, buscada depois que a página carrega, por seu próprio endpoint. Esse é o limite concreto do que o primeiro documento contém — eu não generalizaria além disso sobre o que cada rastreador específico fará em seguida sem testar diretamente suas URLs publicadas.

A consequência para SEO é concreta: o HTML estático que um rastreador lê na primeira busca contém seu conteúdo de fallback, não o conteúdo adiado da ilha. Isso é perfeito para o que Server Islands foram feitas para oferecer — dados personalizados e específicos da sessão (estado de login, contagem do carrinho, recomendações) que não deveriam ser armazenados em cache nem indexados. É errado para o conteúdo principal indexável. Coloque no template principal do Astro tudo o que precisa ranquear e deixe Server Islands cuidarem dos trechos dinâmicos ao redor.

Modos de saída: estático versus servidor e a substituição por rota

O modo de saída padrão do Astro é static — páginas e endpoints são pré-renderizados em HTML no build. Defina output: 'server' em astro.config.mjs e o padrão muda para renderização sob demanda: as páginas são renderizadas por solicitação (com um adapter), o que é útil para autenticação, dados em tempo real ou personalização além do que Server Islands cobrem. De qualquer forma, você pode substituir o padrão por rota: em um projeto com padrão estático, export const prerender = false opta uma rota pela renderização sob demanda; em um projeto com padrão de servidor, export const prerender = true coloca uma rota de volta na pré-renderização do build. Portanto, “meu site é estático” ou “meu site é SSR” raramente é verdade para todas as rotas — verifique a configuração por rota, não apenas a configuração de nível superior. Evidence for this claim Astro uses static output and prerenders routes at build time by default. Scope: Astro default output mode; routes can opt out of prerendering. Confidence: high · Verified: 2026-07-14 Astro: On-demand rendering

Do ponto de vista puramente de SEO, HTML pré-renderizado e HTML sob demanda são equivalentes — ambos entregam HTML completo à primeira solicitação de um rastreador, depois que você confirmou de fato que a rota retorna 200 com a marcação completa. Rotas sob demanda podem transmitir seu HTML em streaming, e dados ou condições de rede lentos podem atrasar trechos posteriores, então uma resposta em streaming não prova automaticamente que todo o conteúdo chegou — verifique, não presuma. A diferença real entre os modos é operacional: conteúdo pré-renderizado fica fixo até o próximo build (ou uma atualização em runtime configurada separadamente) e é servido diretamente da borda da CDN; conteúdo sob demanda está sempre atual, mas depende de seu adapter e runtime estarem saudáveis em produção. Não trate isso como uma decisão de SEO — escolha com base na atualidade dos dados e na operação, depois valide as rotas publicadas, status, redirecionamentos e cabeçalhos de resposta em vez de extrapolar o que funcionou no ambiente local.

View Transitions: seguras para SEO, apesar da aparência de SPA

O <ClientRouter /> do Astro (antes <ViewTransitions />) oferece navegação suave semelhante à de uma SPA usando a View Transitions API e a History API do navegador. O fato importante: ele navega com history.pushState, exatamente o que o Google recomenda para navegação no cliente — o Google alerta que URLs baseadas em fragmentos (#hash) são algo que ele “can’t reliably resolve.” (tradução) «não consegue resolver de forma confiável». O ponto crucial é que View Transitions são um aprimoramento no lado do navegador. Quando o Googlebot rastreia, ele solicita cada URL e recebe uma página HTML normal e completa — a MPA subjacente permanece intacta. As transições afetam apenas o que uma pessoa vê no navegador.

Portanto, não: View Transitions não transformam seu site Astro em uma SPA e não quebram o SEO. Uma lacuna que vale notar: a documentação de View Transitions do Astro não tem uma seção de SEO, provavelmente por isso o mito de que “quebra SEO” persiste. Para verificar seu próprio site, busque algumas URLs diretamente e confirme que cada uma retorna HTML completo — não aceite isso por fé, confira a sua publicação.

Erros comuns de SEO no Astro

1. Presumir que o Astro cuida do seu SEO. Ele cuida do HTML. Meta tags, canônicas, sitemap e schema são responsabilidade sua.
2. Esquecer site: na configuração — seu sitemap não é gerado silenciosamente.
3. Não adicionar o sitemap ao robots.txt — o Astro não fará isso.
4. Carregar a imagem LCP com lazy — substitua no hero por eager + fetchpriority.
5. Colocar conteúdo indexável em uma Server Island — os rastreadores veem o fallback, não o conteúdo, e Server Islands exigem um adapter desde o início.
6. Perseguir uma pontuação perfeita no Lighthouse e parar aí. Velocidade é um sinal de ranking, não o sinal de ranking. Uma página rápida e vazia não ranqueia — conteúdo, links e E-E-A-T ainda fazem o trabalho pesado.
7. Colocar conteúdo indexável apenas dentro de um componente client:only. Diferentemente das outras diretivas client:*, client:only ignora completamente a renderização no servidor — não há HTML para esse componente até o navegador hidratá-lo.
8. Tratar “o Astro é estático/rápido” como garantia de resultado. HTML estático ou sob demanda, ilhas e adapters são mecanismos — não garantem, por si só, rastreabilidade, indexação, rankings ou Core Web Vitals. Valide a rota publicada, não o diagrama da arquitetura.

Onde isso se encaixa no cluster

Astro é uma resposta específica e excepcionalmente amigável para SEO às perguntas que JavaScript SEO levanta sobre renderização, além de ser um frontend popular para configurações de CMS headless. A parte de desempenho se conecta diretamente aos Core Web Vitals no cluster de performance web, e a disciplina de testar “meu conteúdo realmente está no HTML?” é a mesma dos clusters de rastreamento e indexação.

Antipadrões de SEO no Astro

Erros concretos que realmente vejo em sites Astro — não hipóteses. Cada um é uma prevenção, não um diagnóstico: detecte-o antes de publicar.

Tratar o Astro como “otimizado para SEO” por padrão

O Astro oferece HTML estático rápido e limpo, e isso é de fato uma grande vantagem inicial — mas não é o mesmo que meta tags, canônicas, sitemap ou dados estruturados. Por que está errado: equipes publicam páginas sem variação de <title>, sem canonical e sem sitemap porque “o Astro cuida do SEO”, e depois se perguntam por que nada foi indexado como esperado. O que fazer: conecte as props de título/description/canonical do BaseLayout.astro desde o primeiro dia, adicione @astrojs/sitemap e trate isso como etapas obrigatórias do build, não como padrões automáticos.

Esquecer site: em astro.config.mjs

Este é o relato mais comum de “por que meu sitemap está vazio”. Por que está errado: @astrojs/sitemap precisa de uma URL absoluta do site para construir entradas <loc> absolutas — sem definir site:, a integração não produz nada silenciosamente (sem erro, sem aviso). O que fazer: defina site: em astro.config.mjs antes de instalar a integração de sitemap e confira se sitemap-index.xml realmente contém URLs depois do próximo build.

Deixar o sitemap fora de robots.txt

Instalar @astrojs/sitemap não adiciona uma linha Sitemap: ao robots.txt — é uma etapa manual separada que as pessoas presumem ser automática. Por que está errado: os mecanismos de busca ainda podem encontrar o sitemap se você o enviar no Search Console, mas você perde o caminho de descoberta passiva do qual outros bots (e rastreadores próximos de Bing/IndexNow) dependem. O que fazer: adicione Sitemap: https://yoursite.com/sitemap-index.xml ao seu robots.txt em public/ e confirme que ele resolve depois da publicação.

Deixar loading="lazy" padrão na imagem hero

O componente <Image /> do Astro carrega lazy por padrão, o que é correto para imagens abaixo da dobra e errado para a imagem que geralmente é seu elemento LCP. Por que está errado: carregar o hero com lazy atrasa o momento em que o navegador começa a solicitar essa imagem, prejudicando diretamente sua pontuação de Largest Contentful Paint. O que fazer: substitua explicitamente na imagem hero/acima da dobra por loading="eager" e fetchpriority="high", e deixe todas as outras imagens com o padrão lazy.

Colocar conteúdo indexável dentro de uma Server Island

server:defer foi criado para conteúdo personalizado e específico da sessão — contagens do carrinho, estado de login, recomendações — não para nada que você queira ranquear. Por que está errado: o HTML estático que um rastreador lê contém o conteúdo de fallback especificado para a ilha, não o que é buscado no cliente depois do carregamento da página, então qualquer conteúdo principal colocado ali fica invisível para os mecanismos de busca no primeiro rastreamento. O que fazer: mantenha o conteúdo que precisa ranquear no template principal do Astro e reserve Server Islands estritamente para os trechos dinâmicos e personalizados que não deveriam ser indexados de qualquer forma.

Presumir que uma pontuação rápida no Lighthouse é a linha de chegada

Sites Astro apresentam Core Web Vitals fortes quase por padrão, e é tentador parar aí. Por que está errado: velocidade é um sinal de ranking entre muitos — uma página rápida, vazia ou superficial ainda não supera uma página mais lenta com conteúdo, links e profundidade temática melhores. O que fazer: trate desempenho como um requisito básico que você recebe de graça com o Astro e invista o esforço real de otimização na qualidade do conteúdo, nos links internos e no trabalho de dados estruturados/meta que o Astro não faz por você.

Presumir que “estático por padrão” vale para todas as rotas

O modo de saída estática do Astro é o padrão, mas é um padrão, não uma propriedade universal — output: 'server' o altera, e prerender pode ser definido por rota em qualquer direção. Por que está errado: equipes descrevem o site inteiro como “estático” ou “SSR” a partir da configuração de nível superior e nunca verificam rotas individuais, depois se surpreendem quando uma rota se comporta de modo diferente em produção. O que fazer: verifique a configuração prerender por rota para tudo o que estiver analisando e valide a resposta real (código de status, marcação completa, comportamento de redirecionamento) na URL publicada, não no arquivo de configuração.

Colocar conteúdo apenas dentro de um componente client:only

client:only não é o mesmo que client:load/client:idle/client:visible — ele ignora completamente a renderização no servidor. Por que está errado: um componente que usa client:only não produz HTML no servidor, então qualquer conteúdo indexável colocado apenas ali fica invisível para um rastreador que leia a resposta bruta, e é fácil escolher client:only pela “simplicidade” sem perceber o custo para SEO. O que fazer: renderize o conteúdo principal em um componente renderizado no servidor ou no template da página; reserve client:only para widgets exclusivamente interativos sem nada indexável dentro deles.

Resumo de IA

Uma síntese da versão Advanced:

• O modo de saída padrão do Astro pré-renderiza HTML estático no momento do build — para uma rota nesse padrão, o HTML bruto é a página final, então o problema da fila de renderização do Google (a “segunda onda”) não se aplica a ela. Isso é um padrão, não uma propriedade universal: output: 'server' o altera, e prerender pode substituir por rota em qualquer direção.
• A arquitetura de ilhas hidrata apenas componentes marcados com client:*; um componente sem isso envia HTML sem seu próprio JavaScript de hidratação (embora o Astro ainda possa adicionar scripts da página, outras ilhas e JavaScript do roteador em outros lugares). client:only é a exceção — ignora a renderização no servidor, portanto conteúdo indexável não deve viver apenas ali. Isso é hidratação seletiva, não resumability. client:visible evita que o JavaScript abaixo da dobra bloqueie o LCP.
• O Astro não gera nada automaticamente do ponto de vista de SEO — meta tags, canônicas, sitemap, dados estruturados e robots.txt são todos passos deliberados do build. “Astro é automaticamente otimizado para SEO” é um mito.
• @astrojs/sitemap descobre rotas geradas estaticamente — mas você precisa definir site: na configuração (ou ele não faz nada silenciosamente), adicionar a linha do sitemap ao robots.txt por conta própria e incluir explicitamente quaisquer URLs somente de runtime por meio de customPages.
• Content Collections + Zod podem tornar title/description obrigatórios, fazendo o build falhar se uma página não os tiver — uma rede de segurança para SEO.
• astro:assets <Image> converte para WebP, define dimensões (evitando CLS), faz lazy-load por padrão e exige alt. Substitua na imagem LCP por loading="eager" + fetchpriority="high".
• Server Islands (server:defer) exigem um adapter, servem instantaneamente a casca estática + fallback no documento inicial e depois buscam a ilha de forma independente. Rastreadores que leem esse primeiro documento veem o fallback, não a ilha — nunca coloque ali conteúdo indexável.
• Saída estática e sob demanda (servidor) são equivalentes para SEO depois de verificadas — ambas entregam HTML completo aos rastreadores na primeira solicitação, mas rotas sob demanda podem usar streaming, então confirme que a resposta chega completa; escolha o modo pela atualidade dos dados e pela operação, não por SEO.
• View Transitions (<ClientRouter />) usam history.pushState e são seguras para SEO; o Google rastreia as páginas MPA subjacentes normalmente. São um aprimoramento no navegador, não uma conversão para SPA.
• Nada disso é uma garantia de resultado — HTML estático/no servidor, ilhas e adapters são mecanismos, não prova de rastreabilidade, indexação, rankings ou Core Web Vitals. Valide a rota publicada.
• O Astro apresenta números fortes de Core Web Vitals em seu próprio benchmark de 2023 — mais de 50% dos sites Astro passaram na avaliação de CWV do Google, bem acima da linha de base do setor na época; trate isso como um dado datado, não como garantia atual.

Documentação oficial

Documentação de fonte primária do Astro e dos mecanismos de busca.

Astro

• Arquitetura de ilhas — como o Astro remove o JS do lado do cliente e hidrata apenas componentes interativos.
• Referência de diretivas de template — client:load/idle/visible/only e server:defer, incluindo o que client:only ignora.
• Otimização de imagens (astro:assets) — os componentes <Image>/<Picture>, WebP, dimensões e CLS.
• @astrojs/sitemap — geração automática de sitemap, filter, serialize e i18n.
• Server Islands — server:defer, exigência de adapter, conteúdo de fallback e busca adiada no cliente.
• Renderização sob demanda — modos de saída static/server, prerender por rota e streaming de HTML.
• Referência de roteamento — como páginas e endpoints são pré-renderizados por padrão.
• Referência da API de runtime do Astro — tratamento de Response/redirecionamentos e códigos de status padrão.
• Content Collections — conteúdo com tipagem segura e validação de schema Zod.
• View Transitions — <ClientRouter /> e navegação com a History API.

Google

• Entenda os fundamentos de SEO para JavaScript — a fila de renderização, links rastreáveis, a History API e a ressalva de que “nem todos os bots executam JavaScript”.
• Guia aprofundado de como a Busca do Google funciona — rastreamento → renderização → indexação e como SSG remove a etapa de renderização.

Bing / Microsoft

• IndexNow / indexnow.org — o protocolo de envio que combina bem com uma publicação estática do Astro (conecte-o à etapa de publicação para que Bing e Yandex saibam imediatamente de novas páginas).

Citações da fonte

Declarações registradas da documentação do Astro, do Google e de profissionais nomeados. Cada link de mecanismo de busca e documentação é um link profundo que salta para a passagem citada na página-fonte.

Google — a fila de renderização que o Astro contorna

• “Googlebot queues all pages with a 200 HTTP status code for rendering unless a robots meta tag tells Google not to index the page. The page may stay on this queue for a few seconds, but it can take longer than that.” (tradução) «O Googlebot encaminha para a fila de renderização todas as páginas com status HTTP 200, exceto quando uma meta tag robots impede a indexação. A espera pode durar poucos segundos ou se estender além disso.» Ir para a citação
• “not all bots can run JavaScript” (tradução) «nem todos os bots conseguem executar JavaScript» — por que a saída HTML-first ajuda além do Googlebot. Ir para a citação

Documentação do Astro — ilhas, imagens, sitemaps e Server Islands

• “just HTML & CSS, stripping out all client-side JavaScript automatically.” (tradução) «apenas HTML e CSS, removendo automaticamente todo o JavaScript do lado do cliente.» — sobre a arquitetura de ilhas. Ir para a citação
• “infers image dimensions to avoid Cumulative Layout Shift (CLS).” (tradução) «infere as dimensões da imagem para evitar Cumulative Layout Shift (CLS).» — sobre o componente Image. Ir para a citação
• “Your page will be rendered immediately with any specified fallback content as a placeholder. Then, the component’s own contents are fetched on the client and displayed when available.” (tradução) «A página é renderizada de imediato com o conteúdo alternativo definido como espaço reservado; em seguida, o cliente busca o conteúdo do componente e o mostra assim que estiver disponível.» — sobre Server Islands. Ir para a citação

Jason Miller (criador do Preact, que cunhou “arquitetura de ilhas”)

• A hidratação seletiva funciona “rendering HTML pages on the server, and inject[ing] placeholders or slots around highly dynamic regions.” (tradução) «renderizando páginas HTML no servidor e injetando placeholders ou slots ao redor de regiões altamente dinâmicas». — citado em Documentação do Astro: arquitetura de ilhas

Joost de Valk (fundador do Yoast SEO)

• “From an SEO perspective, static HTML on a CDN is a better starting point than most CMSes will ever give you.” (tradução) «Do ponto de vista de SEO, HTML estático em uma CDN é um ponto de partida melhor do que a maioria dos CMSs jamais oferecerá.» — Joost.blog: Guia completo de SEO para Astro

Checklist de SEO para Astro

Uma verificação para confirmar que um site Astro está realmente configurado para busca — não apenas apoiado em uma boa fundação:

• site: está definido em astro.config.mjs (o sitemap não será gerado silenciosamente sem isso).
• @astrojs/sitemap está instalado e a referência ao sitemap foi adicionada manualmente ao robots.txt.
• Existe um robots.txt em public/ e ele não bloqueia nada que você queira indexar.
• Cada página define um title e uma description únicos (de preferência por meio de um BaseLayout.astro compartilhado).
• Há uma canonical autorreferente em cada página, consistente com og:url.
• Content Collections usa um schema Zod que torna title/description obrigatórios (o build falha se estiverem ausentes).
• As imagens usam <Image /> / <Picture />; todas têm alt (a ausência já é um erro de compilação).
• A imagem LCP/hero substitui o lazy-load padrão por loading="eager" e fetchpriority="high".
• Nenhum conteúdo indexável vive em uma Server Island (server:defer) — os rastreadores veem o fallback, e Server Islands precisam de um adapter para funcionar.
• Nenhum conteúdo indexável vive apenas em um componente client:only — ele ignora a renderização no servidor, portanto não há HTML até o navegador hidratar.
• Para qualquer rota que use output: 'server' ou prerender = false por rota, confirme que URLs somente de runtime foram adicionadas explicitamente ao sitemap (customPages) — a descoberta automática do sitemap tem como alvo rotas geradas estaticamente.
• Dados estruturados (JSON-LD) estão no <head> renderizado no servidor.
• Se <ClientRouter /> estiver ativado, faça uma verificação pontual para confirmar que cada URL ainda retorna HTML completo em uma busca direta.
• Rotas sob demanda/no servidor: busque diretamente uma URL de produção e confirme o código de status, o comportamento de redirecionamento e o HTML completo da resposta — não extrapole do ambiente local, pois o comportamento do adapter/runtime pode ser diferente.

Os modelos mentais

1. O HTML bruto é a página final — para o padrão daquela rota. O modo de saída estática do Astro significa que não há onda de renderização para esperar em uma rota pré-renderizada — o que o Googlebot busca é o que será indexado. Esse é um padrão por rota, não uma garantia para todo o site (output: 'server' e prerender por rota podem alterá-lo), então confira a rota, não apenas a configuração de nível superior. Quando se aplica, View Source é a verdade (o oposto de uma SPA CSR) — mas confirme que se aplica antes de tratá-lo como fato.

2. Fundação, não acabamento e não garantia de resultado. O Astro oferece HTML limpo e mecanismos de desempenho fortes gratuitamente. Tudo que sinaliza significado aos mecanismos de busca — meta, canonical, sitemap, schema — é uma etapa deliberada que você adiciona. “Boa arquitetura” ≠ “pronto”, e nenhuma das duas é prova de rastreabilidade, indexação ou rankings — isso ainda precisa ser validado no site publicado.

3. Ilhas são aditivas — exceto client:only. A interatividade fica sobre o HTML, nunca abaixo dele, para client:load/client:idle/client:visible: essas diretivas adicionam JS a um componente sem remover conteúdo da base rastreável. client:only quebra esse padrão — ignora completamente a renderização no servidor, portanto não é aditiva; é uma lacuna real no HTML estático, a menos que você planeje para ela. E a hidratação de ilhas é seletiva, não resumability — não confunda os dois.

4. A casca estática é o que os rastreadores veem. Em Server Islands, o rastreador lê o fallback na casca estática, não o conteúdo adiado. Regra de decisão: conteúdo indexável vai para o template principal; conteúdo personalizado/dinâmico vai para a ilha.

5. Aprimoramento no navegador ≠ mudança estrutural. View Transitions mudam a experiência no navegador (navegação suave por meio de history.pushState), mas não a experiência de rastreamento (cada URL continua sendo uma página HTML completa). Aprimoramentos que mantêm a MPA subjacente intacta são seguros para SEO.

6. Valide no momento do build. Content Collections + Zod transformam “lembre-se de adicionar um título” em “o build não será publicado sem ele”. Coloque os requisitos de SEO no sistema de tipos e eles deixam de ser coisas que você pode esquecer.

SEO para Astro — folha de consulta

O que é automático e o que é responsabilidade sua

Modos de saída

Diretivas de ilhas

• client:load — hidrata imediatamente.
• client:idle — hidrata quando o navegador estiver ocioso.
• client:visible — hidrata quando entrar na área visível (melhor para conteúdo abaixo da dobra; protege o LCP).
• client:only — ignora completamente a renderização no servidor. Não há HTML para esse componente até o navegador hidratá-lo; não é aditivo como os demais.

Regras rápidas

• site: ausente → sem sitemap (silencioso).
• Conteúdo indexável em uma Server Island → o rastreador vê o fallback; Server Islands precisam de um adapter.
• Conteúdo indexável apenas dentro de client:only → não há HTML para ele, ponto final.
• Sitemap cobre rotas estáticas → adicione URLs somente de runtime por meio de customPages.
• View Transitions usam history.pushState → seguras para SEO, com a MPA subjacente intacta.
• Saída estática/no servidor e ilhas são mecanismos, não garantias — valide a rota publicada, o código de status e o HTML completo antes de afirmar um resultado.
• Uma página rápida e vazia ainda não ranqueia — velocidade é um sinal, não o sinal.

Audite o HTML gerado do Astro

Execute isso depois de astro build. Ele verifica o artefato que os rastreadores recebem, não a árvore de componentes-fonte:

find dist -name '*.html' -type f | while IFS= read -r file; do
  canonicals=$(grep -Eio '<link[^>]+rel=["'"']canonical["'"'][^>]*>' "$file" | wc -l | tr -d ' ')
  titles=$(grep -Eio '<title>[^<]*</title>' "$file" | wc -l | tr -d ' ')
  if [ "$canonicals" -ne 1 ] || [ "$titles" -ne 1 ]; then
    printf '%s\ttitles=%s\tcanonicals=%s\n' "$file" "$titles" "$canonicals"
  fi
done

Um resultado vazio significa que cada arquivo HTML gerado tem exatamente um título e uma canonical; isso não valida se os valores estão corretos, portanto faça uma amostragem separada. Essa verificação só cobre o artefato do build — não diz nada sobre rotas sob demanda (output: 'server') ou Server Islands, que não existem como arquivos estáticos.

Faça verificações pontuais das rotas em produção

Para tudo que renderiza sob demanda — rotas output: 'server', prerender = false por rota ou Server Islands — a verificação da saída do build acima não se aplica. Confira a resposta publicada de verdade:

# Replace with your real URLs
for url in "https://example.com/" "https://example.com/some-server-route/"; do
  echo "== $url =="
  curl -sS -D - -o /dev/null "$url" | grep -Ei '^(HTTP|location|cache-control):'
done

Procure o código de status esperado (200 para uma página ativa, um código real de redirecionamento se ela redirecionar — não presuma 302 ou 301 sem verificar) e confirme que curl -sS "$url" retorna marcação completa, não uma casca de fallback, ao verificar uma página que inclui uma Server Island. Faça isso contra produção, não astro dev — o comportamento do adapter e do runtime pode ser diferente do local.

Ferramentas para um site Astro

• @astrojs/sitemap — a integração oficial de sitemap (astro add sitemap). Não se esqueça de site: na configuração.
• astro-seo (npm) — componente comunitário opcional que reúne title, description, Open Graph, Twitter cards e canonical em uma única tag.
• astro-seo-schema (npm) — helper tipado de dados estruturados JSON-LD para Astro.
• astro:assets <Image> / <Picture> — otimização de imagens integrada (WebP/AVIF, dimensões, lazy-load e exigência de alt).
• URL Inspection (Google Search Console) — confirme que seu conteúdo está no HTML rastreado (com o Astro, ele já deveria estar no View Source — uma verificação rápida).
• Um rastreador que renderiza JS — Ahrefs Site Audit ou Screaming Frog para verificar a paridade entre o bruto e o renderizado em todo o site (em rotas pré-renderizadas, eles devem coincidir — confirme, não presuma, e verifique separadamente rotas sob demanda ou Server Islands).
• IndexNow — combine com a etapa de deploy/publicação para que Bing e Yandex saibam imediatamente de novas páginas estáticas.

Teste seus conhecimentos: SEO para Astro

Cinco perguntas rápidas sobre como a arquitetura do Astro afeta o SEO. Escolha uma resposta para cada pergunta e depois confira.

Recursos que valem seu tempo

Minha produção relacionada

• JavaScript SEO: um guia definitivo — os fundamentos de renderização por trás da vantagem da saída HTML-first do Astro.
• Guia para iniciantes de SEO técnico — onde a escolha do framework se encaixa no panorama maior.

Minhas palestras

• How Search Works (SlideShare) — minha explicação de rastreamento, renderização, indexação e ranking — o pipeline que o padrão SSG do Astro encurta. (Aviso permanente: “Esta é a minha compreensão dos sistemas… não será 100% completa ou precisa”.)

Pelo setor

• Documentação do Astro: arquitetura de ilhas — a explicação canônica de como o Astro remove o JS do lado do cliente.
• Documentação do Astro: @astrojs/sitemap — configuração oficial, exigência de site: e opções filter/serialize/i18n.
• Documentação do Astro: Server Islands — server:defer, conteúdo de fallback e o comportamento de busca no cliente que os rastreadores não veem.
• Joost de Valk: Guia completo de SEO para Astro — o guia prático mais confiável, escrito pelo fundador do Yoast; forte em padrões modernos preparados para IA e IndexNow.
• Google Search Central: entenda os fundamentos de SEO para JavaScript — a fila de renderização, links rastreáveis e a orientação da History API seguida por View Transitions do Astro.
• Astro: relatório de desempenho de frameworks web de 2023 — os dados de Core Web Vitals que comparam o Astro a outros frameworks.
• Search Engine Journal: Core Web Vitals, WordPress e Astro — cobertura independente da comparação de desempenho entre Astro e WordPress.

Estatísticas que vale citar

Todos os números abaixo vêm do Relatório de Desempenho de Frameworks Web do Astro de 2023 (e da cobertura do SEJ); trate-os como benchmarks da época de 2023, não como números atuais.

• Mais de 50% dos sites Astro passam na avaliação de Core Web Vitals do Google — acima da média do setor, de aproximadamente 40,5%, e Astro e SvelteKit foram os únicos frameworks importantes a superar essa linha de base (Next.js cerca de 25%, Nuxt cerca de 20%). Fonte
• Taxa de aprovação de INP de 68,8% para o Astro — atribuída à arquitetura MPA (sem navegação orientada por JS), que mantém a thread principal livre. Fonte
• Peso mediano de página de 1,65 MB — o menor do conjunto de dados. Fonte
• LCP: Astro ~0,44 s contra WordPress ~0,81 s — aproximadamente 46% mais rápido na comparação do relatório. Cobertura

Registro de alterações