NNext.js 中文网 GitHub

opengraph-image 和 twitter-image

Open Graph Image 和 Twitter Image 文件约定的 API 参考。

opengraph-image 和 twitter-image 文件约定允许你为路由段设置 Open Graph 和 Twitter 图片。

当用户分享你站点的链接时,它们可用于设置显示在社交网络和消息应用中的图片。

有两种设置 Open Graph 和 Twitter 图片的方式:

与 metadata 导出的优先级#

这些规则同时适用于静态图片文件和生成的图片,遵循 metadata 排序:

  • 页面 metadata:页面从其 metadata 对象或 generateMetadata 函数中显式设置的 openGraph.images 或 twitter.images 会覆盖相应的 opengraph-image 或 twitter-image 文件。这包括同一段中的文件以及从父段继承的图片。
  • 布局 metadata:页面同位置的图片文件可以替换同一段或父段中布局配置的图片。这适用于页面省略相应 images 属性的情况。

例如,如果 app/blog/page.tsx 将 openGraph.images 设置为 ['/custom-og.png'],即使 app/blog/opengraph-image.png 存在,页面也会使用 /custom-og.png。

图片文件(.jpg、.png、.gif)#

通过将 opengraph-image 或 twitter-image 图片文件放在路由段中,可以使用图片文件来设置该段的共享图片。

Next.js 会评估该文件,并自动将相应的标签添加到应用的 <head> 元素中。

文件约定支持的文件类型
opengraph-image.jpg、.jpeg、.png、.gif
twitter-image.jpg、.jpeg、.png、.gif
opengraph-image.alt.txt
twitter-image.alt.txt

小知识:

twitter-image 文件大小不得超过 5MB,opengraph-image 文件大小不得超过 8MB。如果图片文件大小超过这些限制,构建将失败。

opengraph-image#

将 opengraph-image.(jpg|jpeg|png|gif) 图片文件添加到任意路由段中。

<head> output
<meta property="og:image" content="<generated>" />
<meta property="og:image:type" content="<generated>" />
<meta property="og:image:width" content="<generated>" />
<meta property="og:image:height" content="<generated>" />

twitter-image#

将 twitter-image.(jpg|jpeg|png|gif) 图片文件添加到任意路由段中。

<head> output
<meta name="twitter:image" content="<generated>" />
<meta name="twitter:image:type" content="<generated>" />
<meta name="twitter:image:width" content="<generated>" />
<meta name="twitter:image:height" content="<generated>" />

opengraph-image.alt.txt#

在与 opengraph-image.(jpg|jpeg|png|gif) 图片相同的路由段中添加一个配套的 opengraph-image.alt.txt 文件,作为其 alt 文本。

opengraph-image.alt.txt
About Acme
<head> output
<meta property="og:image:alt" content="About Acme" />

twitter-image.alt.txt#

在与 twitter-image.(jpg|jpeg|png|gif) 图片相同的路由段中添加一个配套的 twitter-image.alt.txt 文件,作为其 alt 文本。

twitter-image.alt.txt
About Acme
<head> output
<meta name="twitter:image:alt" content="About Acme" />

使用代码生成图片(.js、.ts、.tsx)#

除了使用字面图片文件外,你还可以使用代码以编程方式生成图片。

通过创建一个默认导出函数的 opengraph-image 或 twitter-image 路由,可以生成路由段的共享图片。

文件约定支持的文件类型
opengraph-image.js、.ts、.tsx
twitter-image.js、.ts、.tsx

小知识:

  • 默认情况下,生成的图片会静态优化(在构建时生成并缓存),除非它们使用请求时 API或未缓存的数据。
  • 你可以使用 generateImageMetadata 在同一个文件中生成多张图片。
  • opengraph-image.js 和 twitter-image.js 是特殊的 Route Handlers,默认会被缓存,除非使用请求时 API或动态配置选项。

生成图片的最简单方法是使用来自 next/og 的 ImageResponse API。

app/about/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// 图片 metadata
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

const interSemiBold = await readFile(
  join(process.cwd(), 'assets/Inter-SemiBold.ttf')
)

// 图片生成
export default async function Image() {
  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        About Acme
      </div>
    ),
    // ImageResponse 选项
    {
      // 为方便起见,我们可以复用导出的 opengraph-image
      // size 配置来同时设置 ImageResponse 的 width 和 height。
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}
app/about/opengraph-image.js
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// 图片 metadata
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

const interSemiBold = await readFile(
  join(process.cwd(), 'assets/Inter-SemiBold.ttf')
)

// 图片生成
export default async function Image() {
  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        About Acme
      </div>
    ),
    // ImageResponse 选项
    {
      // 为方便起见,我们可以复用导出的 opengraph-image
      // size 配置来同时设置 ImageResponse 的 width 和 height。
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}
<head> output
<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="About Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

属性#

默认导出的函数接收以下属性:

params(可选)#

一个 promise,解析为一个对象,该对象包含从根段到 opengraph-image 或 twitter-image 所在段的动态路由参数对象。

小知识:如果你使用 generateImageMetadata,该函数还将接收一个 id 属性,它是一个 promise,解析为 generateImageMetadata 返回的其中一项的 id 值。

app/shop/[slug]/opengraph-image.tsx
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}
app/shop/[slug]/opengraph-image.js
export default async function Image({ params }) {
  const { slug } = await params
  // ...
}
路由URLparams
app/shop/opengraph-image.js/shopundefined
app/shop/[slug]/opengraph-image.js/shop/1Promise<{ slug: '1' }>
app/shop/[tag]/[item]/opengraph-image.js/shop/1/2Promise<{ tag: '1', item: '2' }>

返回值#

默认导出的函数应返回一个 Response。

小知识:ImageResponse 满足此返回类型。

配置导出#

你可以选择通过从 opengraph-image 或 twitter-image 路由导出 alt、size 和 contentType 变量来配置图片的 metadata。

选项类型
altstring
size{ width: number; height: number }
contentTypestring - 图片 MIME 类型

alt#

opengraph-image.tsx | twitter-image.tsx
export const alt = 'My images alt text'

export default function Image() {}
opengraph-image.js | twitter-image.js
export const alt = 'My images alt text'

export default function Image() {}
<head> output
<meta property="og:image:alt" content="My images alt text" />

size#

opengraph-image.tsx | twitter-image.tsx
export const size = { width: 1200, height: 630 }

export default function Image() {}
opengraph-image.js | twitter-image.js
export const size = { width: 1200, height: 630 }

export default function Image() {}
<head> output
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

contentType#

opengraph-image.tsx | twitter-image.tsx
export const contentType = 'image/png'

export default function Image() {}
opengraph-image.js | twitter-image.js
export const contentType = 'image/png'

export default function Image() {}
<head> output
<meta property="og:image:type" content="image/png" />

路由段配置#

opengraph-image 和 twitter-image 是特殊的 Route Handlers,可以使用与 Pages 和 Layouts 相同的路由段配置选项。

示例#

使用外部数据#

此示例使用 params 对象和外部数据来生成图片。

小知识: 默认情况下,生成的图片将进行静态优化。你可以配置单个 fetch 的 options 或路由段的选项来更改此行为。

app/posts/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'

export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await fetch(`https://.../posts/${slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}
app/posts/[slug]/opengraph-image.js
import { ImageResponse } from 'next/og'

export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }) {
  const { slug } = await params
  const post = await fetch(`https://.../posts/${slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

使用 Node.js 运行时和本地资源#

这些示例使用 Node.js 运行时从文件系统获取本地图片,并将其传递给 <img> 的 src 属性,形式为 base64 字符串或 ArrayBuffer。请将本地资源相对于项目根目录放置,而不是相对于示例源文件。

该资源不依赖请求数据,因此在模块作用域中读取一次即可。请参阅可预测的值。

app/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

const logoData = await readFile(join(process.cwd(), 'logo.png'), 'base64')
const logoSrc = `data:image/png;base64,${logoData}`

export default async function Image() {
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}
app/opengraph-image.js
import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

const logoData = await readFile(join(process.cwd(), 'logo.png'), 'base64')
const logoSrc = `data:image/png;base64,${logoData}`

export default async function Image() {
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

将 ArrayBuffer 传递给 <img> 元素的 src 属性不属于 HTML 规范。next/og 使用的渲染引擎支持它,但由于 TypeScript 定义遵循该规范,你需要使用 @ts-expect-error 指令或类似方式来使用此功能。

app/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

const logoData = await readFile(join(process.cwd(), 'logo.png'))
const logoSrc = Uint8Array.from(logoData).buffer

export default async function Image() {
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}
app/opengraph-image.js
import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'

const logoData = await readFile(join(process.cwd(), 'logo.png'))
const logoSrc = Uint8Array.from(logoData).buffer

export default async function Image() {
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

故障排查#

未使用基于文件的图片#

如果页面使用的图片与其同位置的 opengraph-image 或 twitter-image 文件不同:

  1. 检查页面渲染的 og:image 或 twitter:image meta 标签,以找到所选图片的 URL。即使页面的 metadata 指向别处,基于文件的图片路由仍可能提供图片。
  2. 检查页面的 metadata 导出中是否有 openGraph.images 或 twitter.images,包括从共享对象复制的属性。
  3. 完全省略相应的 images 属性以使用同位置的文件。

小知识:将 images 设置为 []、null 或 undefined 仍会覆盖基于文件的图片。对于 Twitter,只有 [] 还会抑制回退到已解析的 Open Graph 图片。

继承的图片消失#

当子路由定义了不含 images 的 openGraph 或 twitter 且没有同位置的图片文件时,它可能会丢失继承的图片。有关如何保留继承字段,请参阅 metadata 合并。

在 catch-all 段中使用图片#

opengraph-image 和 twitter-image 文件不能放在 catch-all([...slug])或可选 catch-all([[...slug]])段内。catch-all 段必须是路由的最后一段,因此像 /blog/[...slug]/opengraph-image 这样的图片路由永远无法匹配。Next.js 会针对这些文件报错。

相反,应从 catch-all 段之外的 Route Handler 提供图片,并从 generateMetadata 中引用它:

app/og/[...slug]/route.tsx
import { ImageResponse } from 'next/og'

export async function GET(
  request: Request,
  { params }: { params: Promise<{ slug: string[] }> }
) {
  const { slug } = await params

  return new ImageResponse(
    <div style={{ fontSize: 64, display: 'flex' }}>{slug.join(' / ')}</div>,
    { width: 1200, height: 630 }
  )
}
app/og/[...slug]/route.js
import { ImageResponse } from 'next/og'

export async function GET(request, { params }) {
  const { slug } = await params

  return new ImageResponse(
    <div style={{ fontSize: 64, display: 'flex' }}>{slug.join(' / ')}</div>,
    { width: 1200, height: 630 }
  )
}
app/blog/[...slug]/page.tsx
import type { Metadata } from 'next'

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string[] }>
}): Promise<Metadata> {
  const { slug } = await params
  const image = `/og/${slug.map(encodeURIComponent).join('/')}`

  return {
    openGraph: { images: [image] },
    twitter: { images: [image] },
  }
}
app/blog/[...slug]/page.js
export async function generateMetadata({ params }) {
  const { slug } = await params
  const image = `/og/${slug.map(encodeURIComponent).join('/')}`

  return {
    openGraph: { images: [image] },
    twitter: { images: [image] },
  }
}

版本历史#

版本变更
v16.0.0params 现在是一个解析为对象的 promise
v13.3.0引入了 opengraph-image 和 twitter-image。
Next.js 中文网