Menu

opengraph-image and twitter-image

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

当用户在社交网络和消息应用中分享你网站的链接时，这些图像会显示出来，它们对此非常有用。

有两种方式可以设置 Open Graph 和 Twitter 图像：

图像文件（.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>
<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>
<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 文件作为其替代文本。

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

twitter-image.alt.txt

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

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

使用代码生成图像（.js、.ts、.tsx）

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

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

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

值得注意的是：

  • 默认情况下，生成的图像是静态优化的（在构建时生成并缓存），除非它们使用 Dynamic API 或未缓存的数据。
  • 你可以使用 generateImageMetadata 在同一个文件中生成多个图像。
  • opengraph-image.js 和 twitter-image.js 是特殊的 Route Handler，默认情况下会被缓存，除非它使用 Dynamic API 或 dynamic config 选项。

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

app/about/opengraph-image.tsx
TypeScript
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
// 图像元数据
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
 
export const contentType = 'image/png'
 
// 图像生成
export default async function Image() {
  // 字体加载，process.cwd() 是 Next.js 项目目录
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )
 
  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>
<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" />

Props

默认导出函数接收以下 props：

params（可选）

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

值得注意的是：如果你使用 generateImageMetadata，该函数还会接收一个 id prop，它是一个 promise，解析为 generateImageMetadata 返回的项目之一的 id 值。

app/shop/[slug]/opengraph-image.tsx
TypeScript
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  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' }>

返回值

默认导出函数应该返回 Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response。

值得注意的是：ImageResponse 满足此返回类型。

配置导出

你可以通过从 opengraph-image 或 twitter-image 路由导出 alt、size 和 contentType 变量来选择性地配置图像的元数据。

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

alt

opengraph-image.tsx
TypeScript
export const alt = 'My images alt text'
 
export default function Image() {}
<head>
<meta property="og:image:alt" content="My images alt text" />

size

opengraph-image.tsx
TypeScript
export const size = { width: 1200, height: 630 }
 
export default function Image() {}
<head>
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

contentType

opengraph-image.tsx
TypeScript
export const contentType = 'image/png'
 
export default function Image() {}
<head>
<meta property="og:image:type" content="image/png" />

Route Segment Config

opengraph-image 和 twitter-image 是专门的 Route Handler，可以使用与 Pages 和 Layouts 相同的 route segment configuration 选项。

示例

使用外部数据

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

值得注意的是： 默认情况下，此生成的图像将被静态优化。你可以配置单个 fetch options 或路由段 options 来改变此行为。

app/posts/[slug]/opengraph-image.tsx
TypeScript
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,
    }
  )
}

使用 Node.js runtime 和本地资源

这些示例使用 Node.js runtime 从文件系统获取本地图像，并将其作为 base64 字符串或 ArrayBuffer 传递给 <img> 的 src 属性。将本地资源放置在项目根目录的相对位置，而不是示例源文件的相对位置。

app/opengraph-image.tsx
TypeScript
import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'
 
export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'), 'base64')
  const logoSrc = `data:image/png;base64,${logoData}`
 
  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
TypeScript
import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'
 
export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer
 
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {/* @ts-expect-error Satori 在运行时接受 ArrayBuffer/typed arrays 作为 <img src> */}
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

版本历史

版本变更
v16.0.0params 现在是解析为对象的 promise
v13.3.0引入 opengraph-image 和 twitter-image。