Next.js Open Graph 图片无法正常显示

为什么 Next.js 预览缺失或显示错误

• 未配置 metadataBase 的相对图片路径。在基于 URL 的元数据字段中使用相对 URL 但未配置 metadataBase 会导致构建错误，而且社交平台也无法抓取相对路径。

• 页面覆盖了 openGraph 并丢失了图片。布局（layout）和页面（page）中的元数据是浅合并的，因此页面的 openGraph 对象会替换掉布局的整个 openGraph，包括其中的图片。

• 图片文件过大。opengraph-image 必须小于 8 MB，twitter-image 必须小于 5 MB，否则构建会失败。

• 你在 localhost 或受保护的预览部署环境中进行了测试。外部平台是从它们自己的服务器抓取数据的，无法访问此类环境。

• 平台缓存了之前的部署版本。修复后请刷新缓存。

如何修复

1. 在 app/layout.tsx 中，设置 metadataBase: new URL('https://your-domain.com')。

2. 当页面设置 openGraph 时，重新包含 images，或者从 generateMetadata 中展开父级图片。

3. 或者在路由段中添加一个 opengraph-image.png 文件。Next.js 会自动为你添加 og:image 及其类型、宽度和高度。

4. 对于动态生成的图片，使用来自 next/og 的 ImageResponse，并设置 size = { width: 1200, height: 630 }。

5. 部署后，使用元标签检查工具检查公开的 URL。

Next.js 应该输出的标签

• og:title、og:description、og:url

• 带有 og:image:width、og:image:height 和 og:image:type 的 og:image

• 来自 opengraph-image.alt.txt 的 og:image:alt

• twitter:card 和 twitter:image（绝对 URL）

你可以使用元标签生成器手动编写这些标签，并与构建输出进行比对。

图片尺寸规则

• opengraph-image：.jpg、.jpeg、.png 或 .gif，最大 8 MB

• twitter-image：相同格式，最大 5 MB

• 1200 x 630 像素是 Next.js 在其示例中使用的尺寸

流式元数据与爬虫

较新版本的 Next.js 可以将来自 generateMetadata 的元数据以流式传输方式输出到 body 中。对于解析 HTML 能力有限的爬虫（如 facebookexternalhit），Next.js 仍会阻止流式渲染，并将标签放入 head 中。它是通过 user agent 来检测这些爬虫的。你可以在 next.config 中使用 htmlLimitedBots 来覆盖该列表。

如何强制刷新缓存

Next.js 无法清除其他平台的缓存。部署后，需要在各平台上刷新：LinkedIn 使用 Post Inspector，Facebook 使用 Sharing Debugger，X、Slack 和 Discord 则可以通过添加新的查询字符串来刷新。刷新工具集合了所有这些平台。

参考来源

• Next.js generateMetadata

• opengraph-image 和 twitter-image