A imagem Open Graph do Next.js não está funcionando

A maioria dos bugs de pré-visualização do Next.js vem da API de Metadados: a falta de uma metadataBase, um objeto openGraph que substitui o pai ou um arquivo de imagem que ultrapassa o limite.

Última atualização

Verifique sua URL

Atualizar prévia

Gerar tags

Solução rápida


  1. Defina metadataBase no layout raiz para que os caminhos relativos de imagem se tornem URLs absolutas.

  2. Repita o objeto openGraph completo em qualquer página que o substitua.

  3. Mantenha opengraph-image abaixo de 8 MB e twitter-image abaixo de 5 MB.

  4. Verifique a URL implantada com o verificador de meta tags, não o localhost.


Por que a pré-visualização do Next.js está ausente ou incorreta

  • Caminhos de imagem relativos sem metadataBase. Uma URL relativa em um campo de metadados baseado em URL sem metadataBase causa um erro de build, e as plataformas não conseguem buscar caminhos relativos de qualquer forma.

  • Uma página substitui openGraph e perde a imagem. Os metadados de layouts e páginas são mesclados de forma superficial (shallow merge), portanto, o objeto openGraph de uma página substitui todo o openGraph do layout, incluindo a imagem.

  • O arquivo de imagem é muito grande. O opengraph-image deve ter menos de 8 MB e o twitter-image menos de 5 MB, caso contrário, o build falhará.

  • Você testou no localhost ou em um deploy de visualização protegido. As plataformas fazem a busca a partir de seus próprios servidores e não conseguem acessá-lo.

  • A plataforma armazenou em cache um deploy anterior. Atualize-a após a correção.

Como corrigir

  1. Em app/layout.tsx, defina metadataBase: new URL('https://seu-dominio.com').

  2. Quando uma página definir openGraph, inclua images novamente, ou utilize o operador spread com as imagens pai de generateMetadata.

  3. Ou adicione um arquivo opengraph-image.png ao segmento da rota. O Next.js adiciona og:image, seu tipo, largura e altura para você.

  4. Para imagens geradas, use ImageResponse de next/og com size = { width: 1200, height: 630 }.

  5. Faça o deploy e, em seguida, verifique a URL pública com o verificador de meta tags.

Tags que o Next.js deve gerar

  • og:title, og:description, og:url

  • og:image com og:image:width, og:image:height e og:image:type

  • og:image:alt a partir de opengraph-image.alt.txt

  • twitter:card e twitter:image (URL absoluta)

Você pode escrever essas tags manualmente com o gerador de meta tags e compará-las com o seu build.

Regras de tamanho de imagem

  • opengraph-image: .jpg, .jpeg, .png ou .gif, máximo de 8 MB

  • twitter-image: mesmos tipos, máximo de 5 MB

  • 1200 x 630 px é o tamanho que o Next.js usa em seus exemplos

Streaming de metadados e rastreadores

Versões mais recentes do Next.js podem fazer streaming de metadados de generateMetadata para o body. Para bots com suporte limitado a HTML, como o facebookexternalhit, o Next.js ainda bloqueia a renderização e coloca as tags no head. Ele detecta esses bots pelo user agent. Você pode sobrescrever a lista com htmlLimitedBots no next.config.

Como forçar uma atualização

O Next.js não pode limpar o cache de outra plataforma. Após o deploy, atualize cada plataforma: Post Inspector para o LinkedIn, o Sharing Debugger para o Facebook, uma nova query string para o X, Slack e Discord. A ferramenta de atualização tem todos eles.

Fontes

Perguntas Frequentes

Por que o og:image do meu Next.js é uma URL relativa?

O metadataBase não está definido. Defina-o no layout raiz para que o Next.js transforme caminhos relativos em URLs absolutas.

Por que minha página perde o og:image do layout?

O Next.js mescla os metadados superficialmente. Se uma página define openGraph, ela substitui o objeto openGraph do layout, portanto adicione as imagens novamente na página.

Qual é o limite de tamanho de arquivo para opengraph-image no Next.js?

8 MB para opengraph-image e 5 MB para twitter-image. Arquivos maiores causam falha na compilação.

Verifique sua página e atualize a prévia

Cole sua URL no verificador gratuito para ver as tags exatas que cada aplicativo lê. Assim que as tags estiverem corretas, use a ferramenta de atualização para limpar a pré-visualização antiga.

Verifique sua URL

Atualizar pré-visualização

Gerar tags

Guias relacionados

O card do X (Twitter) não está aparecendo ou não está atualizando

O X cria o card a partir das tags twitter:, usando as tags og: como alternativa. Não há mais um validador que atualize o cache, então a solução é usar tags corretas acompanhadas de uma nova URL.

A pré-visualização social do Framer não está atualizando

O Framer define uma prévia para redes sociais em todo o site, substituições por página e imagens individuais para itens do CMS. Se a nova imagem já estiver no ar, mas a antiga ainda aparecer, o cache da plataforma é o motivo.

A imagem Open Graph do Webflow não está funcionando

O Webflow define o Open Graph por página, nunca globalmente. As páginas de modelo do CMS precisam de um campo de Imagem, e todas as imagens dessa coleção devem ter o mesmo tamanho.