Idiomas

SEO para Gatsby

Como otimizar um site Gatsby para busca — os quatro caminhos de renderização do Gatsby (SSG, DSG, SSR e somente de cliente) e o que cada um significa para rastreabilidade, a Head API moderna versus o react-helmet legado, sitemaps, canônicas, SEO de imagens, o custo do pacote React nos CWV e o risco de manutenção na era Netlify.

Publicado pela primeira vez: 26 de jun. de 2026 · Última atualização: 3 de ago. de 2026 · Avançado
Idiomas
AIEscrito porAI v2
1 sinal de evidência nesta página

O Gatsby tem quatro opções de renderização: SSG (o padrão — páginas pré-renderizadas para HTML estático em gatsby build), DSG (geração estática adiada na primeira requisição), SSR (renderização no servidor por requisição via Gatsby Functions) e rotas somente de cliente (renderizadas inteiramente no navegador). A maioria dos sites Gatsby usa SSG, que oferece HTML totalmente renderizado aos crawlers na primeira busca, sem esperar por uma fila de renderização — uma base forte de SEO, muito melhor que um aplicativo React puramente client-side. Mas essa base não é universal: páginas DSG e SSR geram HTML fora da etapa de build e precisam de suas próprias verificações em produção, e não se deve presumir que rotas somente de cliente expõem conteúdo específico da rota no HTML inicial. Qualquer que seja o caminho, o Gatsby ainda envia o runtime React completo (~200KB+) e o hidrata no cliente — um custo de Core Web Vitals, não de rastreabilidade. A forma atual de administrar metadados é a Gatsby Head API integrada (v4.19+), que funciona nos quatro caminhos e substitui gatsby-plugin-react-helmet. As armadilhas recorrentes são tags canônicas duplicadas, páginas de rascunho/órfãs vazando para sitemaps, texto alt ausente, a armadilha de sitemap apenas de produção, rotas DSG/SSR/somente de cliente que exigem verificações explícitas de sitemap e comportamento em produção e um framework cuja manutenção desacelerou bastante desde a aquisição pela Netlify em 2023.

TL;DR — O Gatsby tem quatro opções de renderização — SSG (o padrão), DSG, SSR e rotas somente de cliente — e elas não colocam o conteúdo no HTML bruto da mesma forma. O SSG pré-renderiza para HTML estático no momento do build (gatsby build), então o conteúdo está no HTML bruto antes da primeira requisição do crawler — sem Web Rendering Service nem fila de renderização. O DSG adia a geração até a primeira requisição; o SSR gera por requisição no servidor; as rotas somente de cliente não renderizam nada específico da rota até o navegador executar o JavaScript. Qualquer que seja o caminho que entregue a página, o Gatsby hidrata um pacote React completo (~200KB+) no cliente, o que é um custo de Core Web Vitals, não de rastreabilidade. A abordagem atual de metadados é a Gatsby Head API integrada (v4.19+), que funciona nos quatro caminhos e substitui gatsby-plugin-react-helmet. Os modos de falha recorrentes são tags canônicas duplicadas (Head API + react-helmet disparando juntos), páginas rascunho/órfãs vazando para sitemaps, a armadilha de sitemap apenas de produção, texto alt ausente em GatsbyImage, inconsistência de barra final e rotas DSG/SSR/somente de cliente que nunca passaram por uma verificação em produção. E há um elefante na sala: desde a aquisição da Gatsby pela Netlify em 2023, a manutenção desacelerou bastante.

As quatro opções de renderização do Gatsby — e por que importam para SEO

O Google processa páginas JavaScript em três fases — rastreamento, depois renderização e então indexação — e a renderização ocorre em uma passagem separada, a partir de uma fila que usa Chromium headless. A orientação do próprio Google é direta sobre por que você não deve depender disso: “Server-side or pre-rendering is still a great idea because it makes your website faster for users and crawlers, and not all bots can run JavaScript.” Tradução: “A renderização no servidor ou a pré-renderização continua sendo uma ótima ideia porque torna seu site mais rápido para usuários e crawlers, e nem todos os bots conseguem executar JavaScript.”

Um site Gatsby não é universalmente HTML estático gerado no build — o Gatsby oferece quatro caminhos distintos de renderização, escolhidos por página ou template Evidence for this claim gatsby build writes production output, including generated HTML, to the public directory. Scope: Gatsby production builds. Confidence: high · Verified: Gatsby CLI: build :

  • SSG (Static Site Generation) — o padrão. gatsby build emite HTML estático totalmente renderizado em /public para a página. A primeira busca de HTML bruto do Googlebot já contém o conteúdo completo — texto, links e metadados. Este é o caminho seguro e de baixo risco, usado pela maioria das páginas Gatsby.
  • DSG (Deferred Static Generation). A geração é adiada até a primeira requisição da página, em vez de ocorrer para todas as páginas durante o build — útil para sites com enormes quantidades de páginas de pouco tráfego, quando um build completo seria lento. O build sozinho não informa o que um crawler vê; o HTML da página não existe até que algo a solicite, portanto o comportamento da primeira requisição e do cache precisa de sua própria verificação, não apenas de um log de build.
  • SSR (Server-Side Rendering). A página é renderizada por requisição, usando dados do momento da requisição, via Gatsby Functions. Como roda durante a requisição, páginas SSR precisam de verificações de produção que uma página gerada no build não precisa: status da resposta, cabeçalhos de cache, comportamento diante de timeout e o que um crawler vê em uma resposta vazia ou de erro — nada disso aparece em um build local bem-sucedido.
  • Rotas somente de cliente. Elas renderizam inteiramente no navegador e não recebem conteúdo específico da rota no HTML inicial — o mesmo perfil de um aplicativo React puramente client-side. Não presuma que o Google (ou qualquer crawler) verá algo específico da página até o JavaScript rodar; trate-as como dependentes de JS por projeto. Isso é adequado para conteúdo protegido/autenticado, mas errado para qualquer coisa que você queira indexar com conteúdo.

A hidratação React (ReactDOMClient.hydrateRoot()) acontece no cliente sobre o HTML produzido por qualquer um desses caminhos, exclusivamente para adicionar interatividade — essa parte é igual independentemente do caminho de renderização e é uma preocupação separada do caminho que gerou a página (mais sobre o custo da hidratação abaixo).

Compare SSG/DSG/SSR com um aplicativo React puramente client-side, que entrega um <div id="root"> vazio e depende do navegador (ou do renderizador) para construir a página. A maioria das páginas Gatsby envia HTML significativo por padrão — essa é a vantagem de indexabilidade, e ela é real, mas é uma propriedade de cada página, não uma garantia do framework. Opções de renderização e ferramentas de imagem não garantem sozinhas Core Web Vitals, indexação ou rankings; verifique a saída real de produção para o caminho usado por cada rota.

A desvantagem comum a SSG/DSG/SSR é de performance, não de rastreabilidade: o Gatsby envia o runtime React completo a todas as páginas e as reidrata. Mais sobre isso, e sobre a comparação com Astro, abaixo.

Gatsby Head API versus gatsby-plugin-react-helmet

Esta é a pergunta única mais importante de “você está fazendo do jeito moderno?” no SEO do Gatsby.

A abordagem legada — gatsby-plugin-react-helmet. Durante anos, a forma padrão de definir <title>, meta description e outras tags de head era usar a biblioteca react-helmet com esse plugin. A função do plugin era fornecer suporte a SSR para o react-helmet — sem ele, suas title/meta tags só apareceriam depois da execução do JS, não no HTML bruto, anulando o propósito. Funciona, mas tem problemas conhecidos com React Hooks e renderização concorrente, além de um bug de título em abas em segundo plano que você corrige com defer={false}.

A abordagem moderna — a Gatsby Head API (v4.19+). O Gatsby agora tem uma forma integrada de adicionar elementos ao head: uma exportação nomeada Head de qualquer arquivo de página ou template. Evidence for this claim Gatsby pages and templates can export a named Head function to add head elements. Scope: Gatsby Head API. Confidence: high · Verified: Gatsby: Head API 

export const Head = () => (
  <>
    <title>Page Title</title>
    <meta name="description" content="..." />
  </>
)

Ela recebe props úteis — location.pathname, params, data (da consulta GraphQL da página) e pageContext — e elimina duplicatas de tags que compartilham uma prop id (a última vence), embora executar dois mecanismos diferentes de tags de head ao mesmo tempo (Head API e uma chamada remanescente do react-helmet) ainda possa causar conflito mesmo com a deduplicação. Ela funciona somente em arquivos de página e templates, não em componentes arbitrários. As vantagens sobre o react-helmet: nenhum pacote de terceiros, nenhum wrapper Provider e ordem determinística das tags com streaming do React 18. Use a Head API em todos os projetos novos e planeje migrar os existentes.

A Head API funciona da mesma forma nos quatro caminhos de renderização — SSG, DSG, SSR e rotas somente de cliente suportam uma exportação Head. O que muda é quando sua saída chega ao HTML que um crawler pode buscar: no SSG ela é gravada durante o build; no DSG e no SSR é gerada na primeira requisição ou por requisição; em uma rota somente de cliente ela não está no HTML inicial. Não presuma que “adicionei uma exportação Head” equivale a “isso está no HTML bruto de todas as rotas” — verifique a saída de produção real (view-source: ou curl) para o caminho de cada rota, não apenas uma página representativa.

O bug de “meta tags no DevTools, mas não na fonte”. Um sintoma clássico de SEO no Gatsby: suas title/meta tags aparecem no Chrome DevTools, mas faltam em view-source:. A causa é que o DevTools mostra o DOM hidratado (depois da execução do JS), enquanto view-source mostra o HTML bruto. Se as tags aparecem apenas no DevTools, seu componente de SEO está renderizando no cliente em vez de ser gravado na saída estática do Gatsby — geralmente porque é usado como componente comum, e não como (ou dentro da) exportação Head da página. Verifique sempre o HTML bruto, não o DevTools.

Conectando um componente de SEO (a camada de dados GraphQL)

A camada de dados do Gatsby é GraphQL e é assim que você alimenta suas páginas com metadados.

  • useStaticQuery extrai padrões globais de siteMetadata (title, description, siteUrl) definidos em gatsby-config.js.
  • Consultas GraphQL no nível da página passam uma prop data diretamente para a exportação Head — sem configuração extra.
  • O padrão comum é prop || fallback de siteMetadata: use o valor da página se ele existir; caso contrário, use o padrão do site.

Uma exportação Head que recebe dados da página se parece com:

export const Head = ({ data }) => (
  <>
    <title>{data.post.title}</title>
    <meta name="description" content={data.post.excerpt} />
  </>
)

Sitemaps: gatsby-plugin-sitemap (e suas armadilhas)

Instale gatsby-plugin-sitemap e configure-o em gatsby-config.js. Algumas coisas costumam confundir:

  • Ele gera sitemap-index.xml, não /sitemap.xml. Envie a URL do índice ao Google Search Console — não envie /sitemap.xml esperando que ele resolva.
  • Ele só roda em builds de produção. Não faz nada em gatsby develop. Para testá-lo, execute gatsby build && gatsby serve. As pessoas abrem relatos de “meu sitemap sumiu” que na verdade significam “eu nunca executei um build de produção”.
  • createLinkInHead: true por padrão adiciona automaticamente a referência ao sitemap no head do HTML.
  • Ele sempre exclui /dev-404-page, /404 e /offline-plugin-app-shell-fallback.
  • <priority> e <changefreq> são ignorados pelo Google — a documentação do plugin afirma isso diretamente. Concentre-se em um <lastmod> preciso.
  • entryLimit tem como padrão 45 000 URLs por arquivo.

Excluir rascunhos é sua responsabilidade. O Gatsby constrói tudo o que encontra, então conteúdo em rascunho vai direto para o sitemap se você não o filtrar. Faça isso em gatsby-node.js com um filtro GraphQL (por exemplo, excluindo entradas sem data de publicação), não escondendo-o em um componente React — nesse momento ele já foi construído e listado.

DSG, SSR e rotas somente de cliente exigem uma decisão explícita de sitemap. O gatsby-plugin-sitemap reflete o que consegue ver no momento do build. Uma página SSG é simples — existe como arquivo estático, portanto é naturalmente elegível para sitemap. O HTML de uma página DSG ainda não existe durante o build (é gerado na primeira requisição), uma página SSR nunca tem HTML fixo e uma rota somente de cliente não tem conteúdo específico da rota para indexar em primeiro lugar. Não presuma que alguma delas está no sitemap (ou deveria estar) só porque a rota existe — decida página por página se ela pertence e verifique se o sitemap-index.xml gerado realmente reflete essa decisão, em vez de uma suposição feita no build.

Arquivo robots.txt: gatsby-plugin-robots-txt

gatsby-plugin-robots-txt gera robots.txt durante o build. O detalhe útil para SEO é a consciência do ambiente: ele lê process.env.GATSBY_ACTIVE_ENV e depois process.env.NODE_ENV, permitindo servir regras diferentes por ambiente. O uso clássico é bloquear crawlers em deploys de preview/branch da Netlify para que as URLs de homologação não sejam indexadas por acidente, mantendo a produção aberta.

URLs canônicas (e o bug da canônica duplicada)

Duas abordagens viáveis:

  1. gatsby-plugin-canonical-urls adiciona um <link rel="canonical"> a todas as páginas. Defina stripQueryString: true para que /blog?tag=foo e /blog não sejam tratados como páginas canônicas separadas — recomendado para a maioria dos sites.
  2. A Head API, definindo as canônicas por conta própria a partir de location.pathname:
export const Head = ({ location }) => (
  <link rel="canonical" href={`https://example.com${location.pathname}`} />
)

O bug da canônica duplicada. Este é um problema conhecido e fácil de encontrar: se você usa gatsby-plugin-canonical-urls e uma tag canônica do react-helmet ao mesmo tempo, emite duas tags <link rel="canonical">. Escolha um mecanismo. (Se estiver usando react-helmet, gatsby-plugin-react-helmet-canonical-urls é a opção compatível com helmet; na Head API, defina a canônica ali e remova o plugin.)

Barras finais. As páginas Gatsby podem ser acessíveis com e sem barra final, e o componente <Link> do Gatsby usa roteamento client-side pela History API — o que contorna os redirecionamentos 301 no servidor que você normalmente usaria para normalizar barras finais. Decida uma forma, imponha-a no nível do host/CDN e mantenha as canônicas consistentes.

SEO de imagens: gatsby-plugin-image

gatsby-plugin-image é genuinamente um dos pontos fortes do Gatsby. Dois componentes:

  • StaticImage — para imagens cujo caminho é conhecido e fixado durante o build.
  • GatsbyImage — para imagens dinâmicas vindas do GraphQL.

O que ele faz automaticamente: vários tamanhos, formatos WebP/AVIF, carregamento lazy e breakpoints (750/1080/1366/1920px). Ele também gera placeholders (desfocados, de cor dominante ou SVG rastreado) que reservam espaço e evitam Cumulative Layout Shift — uma métrica de Core Web Vitals. Como as dimensões são definidas, você evita CLS; formatos modernos e carregamento lazy ajudam o LCP.

A única coisa que ele não faz é escrever o alt text. Isso é responsabilidade sua, sempre — alt ausente em GatsbyImage é uma das falhas de SEO mais comuns no Gatsby. (Migrando do antigo pacote gatsby-image? Existe um codemod: npx gatsby-codemods gatsby-plugin-image.)

Dados estruturados (JSON-LD)

O formato preferido do Google para dados estruturados é JSON-LD, e a forma limpa de adicioná-lo no Gatsby moderno é pela Head API com uma tag de script:

export const Head = ({ data }) => (
  <script type="application/ld+json">
    {JSON.stringify({
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": data.post.title,
    })}
  </script>
)

gatsby-plugin-next-seo oferece componentes JSON-LD pré-construídos se você preferir não criá-los manualmente. Uma confusão frequente que vale esclarecer: gatsby-plugin-manifest não é um plugin de dados estruturados — ele gera o manifesto de aplicativo web da PWA (ícones, cor do tema), sem relação com schema.

O pacote React e os Core Web Vitals

Esta é a verdadeira fraqueza do Gatsby em relação aos geradores sem JS.

  • Hidratação completa (o padrão do Gatsby 1–4) hidrata toda a árvore React e envia um runtime React de 200KB+ para todas as páginas. O HTML é pré-renderizado, então isso não prejudica a rastreabilidade — mas afeta diretamente a velocidade de carregamento e os CWV.
  • Hidratação parcial (Gatsby 5, experimental) hidrata apenas componentes marcados com "use client" e deixa o restante como HTML estático, reduzindo o JS enviado e melhorando diretamente TTI e CWV. As limitações são reais: apenas builds de produção, ainda beta e incompatível com emotion, styled-components e gatsby-plugin-offline.

A conclusão é: o payload JS do Gatsby é um problema de performance, não de indexabilidade. O Googlebot ainda renderiza JS para avaliar sinais de experiência de página, então o pacote pode custar CWV mesmo quando seu conteúdo indexa bem.

Gatsby versus Astro para SEO

Se você está escolhendo um framework estático hoje, esta é a comparação que mais importa para SEO.

DimensãoGatsbyAstro
JS enviado ao navegador200KB+ (runtime React completo)~5KB (apenas ilhas interativas)
Modelo de renderizaçãoSSG → SPA (hidratação completa)SSG → MPA (hidratação zero por padrão)
Velocidade do build (40 páginas)2–3 minutosMenos de 10 segundos
Ecossistema de plugins de SEOMaduro (gatsby-plugin-*)Em crescimento
Impacto no crawl budgetMaior (mais JS para o Google renderizar)Menor
Futuro do frameworkIncerto (propriedade da Netlify, atividade reduzida)Ativo, em crescimento

Ambos pré-renderizam HTML indexável — nisso há empate. A diferença é o imposto do JS: as ilhas do Astro enviam uma fração do JavaScript, o que uma comparação da Vaihe resume assim: “Reduced JavaScript execution conserves crawl budget and accelerates page scanning.” Tradução: “A execução de menos JavaScript preserva o crawl budget e acelera a varredura das páginas.” (Uma ressalva histórica do outro lado: o tratamento de imagens do Astro não tinha largura/altura automáticas no momento daquela comparação, o que produzia avisos do Lighthouse — confira a documentação atual do Astro, pois isso pode já ter sido resolvido.)

Para ver como o campo inteiro se compara, consulte o hub de geradores de sites estáticos.

A parte honesta: a trajetória de manutenção do Gatsby

Não vou dourar a pílula, mas também não vou tratar isso como catástrofe.

A Netlify adquiriu a Gatsby Inc. em fevereiro de 2023. A Gatsby Cloud foi encerrada e os clientes foram transferidos para a Netlify; a Netlify afirmou que a aquisição “não afetaria o Gatsby JS”. Desde então, a atividade desacelerou bastante. Uma discussão muito lida na comunidade no GitHub (#39062) argumenta que o Gatsby está efetivamente abandonado — poucos commits, sem suporte ao React 19, um roadmap de 2024 que não foi entregue e o serviço de telemetria desligado. Os mantenedores descreveram o estado atual como correções de segurança, atualizações limitadas de dependências e correções de bugs fáceis de resolver.

O que isso significa para equipes de SEO. Para um site Gatsby existente, nada disso é uma emergência — ele compila, indexa e funciona. O risco é a deterioração do ecossistema ao longo do tempo: SEO depende de plugins (gatsby-plugin-sitemap, imagem, canonical-urls), e plugins envelhecidos (por exemplo, gatsby-source-shopify diante da descontinuação da API) podem quebrar e degradar a indexação silenciosamente. Para um projeto novo, leve isso a sério — os frameworks para os quais as pessoas estão migrando são Astro e Next.js.

Checklist de produção: verifique todos os caminhos de renderização

Uma sessão local de gatsby develop ou até um log limpo de gatsby build não prova o que um crawler realmente recebe. Como SSG, DSG, SSR e rotas somente de cliente geram HTML de maneiras diferentes, verifique o comportamento de produção por caminho em vez de presumir que uma página representativa cobre todos eles:

  • Conteúdo do HTML bruto. Para cada caminho de renderização em uso, busque uma URL real de produção com curl -s <url> ou view-source: — não com DevTools — e confirme que o conteúdo, o título e as meta tags que um crawler veria estão realmente ali.
  • Metadados (saída da exportação Head). Confirme que as tags da exportação Head chegam a esse HTML bruto. É aqui que DSG/SSR diferem mais de SSG: as tags existem no seu código de qualquer forma, mas apenas uma busca de produção prova que chegaram à resposta.
  • Status HTTP. Verifique o status da resposta em produção, especialmente para rotas SSR e DSG — uma página que renderiza bem localmente pode retornar 500 em produção na primeira requisição ou sob carga de maneiras que um build nunca revela.
  • Comportamento de cache. A saída SSG é um arquivo estático com cache previsível. O DSG faz cache depois da primeira requisição — confirme que a segunda é rápida e correta, não apenas a primeira. As respostas SSR dependem dos cabeçalhos de cache e da camada de hospedagem; verifique se conteúdo obsoleto ou por requisição não é servido ao visitante errado.
  • Comportamento de falha e estado vazio. Para páginas SSR e DSG apoiadas por dados do momento ou da primeira requisição, confira o que um crawler vê se a busca desses dados falhar ou retornar vazio — um estado de erro não tratado não é a mesma página testada localmente com dados corretos.
  • Geração e exclusões do sitemap. Confirme novamente que isso só acontece em um build de produção (gatsby build && gatsby serve, nunca gatsby develop) e que as exclusões esperadas — rascunhos, rotas somente de cliente e qualquer item que você decidiu não listar — realmente estão ausentes do sitemap-index.xml gerado, não apenas da sua intenção.

Nada disso é opcional por caminho de renderização — um gatsby build bem-sucedido prova a saída SSG, não o comportamento DSG, SSR ou somente de cliente.

Erros comuns de SEO no Gatsby

  1. Ainda usar gatsby-plugin-react-helmet — legado; migre para a Head API.
  2. Meta tags no DevTools, mas não na fonte da página — o componente de SEO está renderizando no cliente; confira view-source:, não o DevTools.
  3. Conteúdo de rascunho em sitemaps — filtre rascunhos em gatsby-node.js com GraphQL, não em um componente React.
  4. Páginas órfãs de src/pages — o Gatsby cria rotas automaticamente para tudo ali; arquivos obsoletos são compilados e chegam ao sitemap.
  5. Tags canônicas duplicadas — gatsby-plugin-canonical-urls + react-helmet disparando juntos.
  6. Inconsistência de barra final — o roteamento client-side de <Link> contorna redirecionamentos de barra final no servidor.
  7. Não remover strings de consulta das canônicas — defina stripQueryString: true.
  8. Texto alternativo omitido em GatsbyImage — ele não é gerado automaticamente.
  9. Enviar /sitemap.xml — o arquivo real é /sitemap-index.xml.
  10. Testar o sitemap em gatsby develop — ele só é gerado durante gatsby build.
  11. Alternar noindex pelo estado React — o Google pode já ter processado o HTML bruto; e, ao encontrar noindex no HTML bruto, pode pular a renderização. Mantenha decisões de noindex no HTML estático ou nos cabeçalhos do servidor.

Para os fundamentos de renderização JavaScript por trás de tudo isso, consulte o hub pai de JavaScript SEO.

Add an expert note

Pin an expert quote

New person? Create their unclaimed profile at /admin/experts/ → Pin a quote first.