opengraph-image 和 twitter-image

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

当用户在社交网络和即时通讯应用中分享你网站的链接时，这些图片会显示出来，因此它们非常有用。

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

使用图片文件 (.jpg, .png, .gif)
使用代码生成图片 (.js, .ts, .tsx)

图片文件 (.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`

`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

关于 Acme

<head>

<meta property="og:image:alt" content="关于 Acme" />

`twitter-image.alt.txt`

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

twitter-image.alt.txt

关于 Acme

<head>

<meta property="twitter:image:alt" content="关于 Acme" />

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

除了使用实际图片文件外，你还可以使用代码以编程方式生成图片。

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

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

值得注意的是：

默认情况下，生成的图片是静态优化的 (在构建时生成并缓存)，除非它们使用动态函数或未缓存的数据。

你可以使用 generateImageMetadata 在同一文件中生成多个图片。

opengraph-image.js 和 twitter-image.js 是特殊的路由处理程序，默认情况下会被缓存，除非它们使用动态函数或动态配置选项。

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

app/about/opengraph-image.tsx

import { ImageResponse } from "next/og";
 
export const runtime = "edge";
 
// 图片元数据
export const alt = "关于 Acme";
export const size = {
  width: 1200,
  height: 630,
};
 
export const contentType = "image/png";
 
// 图片生成
export default async function Image() {
  // 字体
  const interSemiBold = fetch(
    new URL("./Inter-SemiBold.ttf", import.meta.url)
  ).then((res) => res.arrayBuffer());
 
  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: "white",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        关于 Acme
      </div>
    ),
    // ImageResponse 选项
    {
      // 为了方便，我们可以重用导出的 opengraph-image
      // size 配置来设置 ImageResponse 的宽度和高度。
      ...size,
      fonts: [
        {
          name: "Inter",
          data: await interSemiBold,
          style: "normal",
          weight: 400,
        },
      ],
    }
  );
}

app/about/opengraph-image.js

import { ImageResponse } from "next/og";
 
export const runtime = "edge";
 
// 图片元数据
export const alt = "关于 Acme";
export const size = {
  width: 1200,
  height: 630,
};
 
export const contentType = "image/png";
 
// 图片生成
export default async function Image() {
  // 字体
  const interSemiBold = fetch(
    new URL("./Inter-SemiBold.ttf", import.meta.url)
  ).then((res) => res.arrayBuffer());
 
  return new ImageResponse(
    (
      // ImageResponse JSX 元素
      <div
        style={{
          fontSize: 128,
          background: "white",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        关于 Acme
      </div>
    ),
    // ImageResponse 选项
    {
      // 为了方便，我们可以重用导出的 opengraph-image
      // size 配置来设置 ImageResponse 的宽度和高度。
      ...size,
      fonts: [
        {
          name: "Inter",
          data: await interSemiBold,
          style: "normal",
          weight: 400,
        },
      ],
    }
  );
}

<head>

<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="关于 Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

参数

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

`params` (可选)

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

app/shop/[slug]/opengraph-image.tsx

export default function Image({ params }: { params: { slug: string } }) {
  // ...
}

app/shop/[slug]/opengraph-image.js

export default function Image({ params }) {
  // ...
}

路由	URL	`params`
`app/shop/opengraph-image.js`	`/shop`	`undefined`
`app/shop/[slug]/opengraph-image.js`	`/shop/1`	`{ slug: '1' }`
`app/shop/[tag]/[item]/opengraph-image.js`	`/shop/1/2`	`{ tag: '1', item: '2' }`
`app/shop/[...slug]/opengraph-image.js`	`/shop/1/2`	`{ slug: ['1', '2'] }`

返回值

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

配置导出

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

选项	类型
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - 图片 MIME 类型

`alt`

opengraph-image.tsx

export const alt = "我的图片替代文本";
 
export default function Image() {}

opengraph-image.js

export const alt = "我的图片替代文本";
 
export default function Image() {}

<head>

<meta property="og:image:alt" content="我的图片替代文本" />

`size`

opengraph-image.tsx

export const size = { width: 1200, height: 630 };
 
export default function Image() {}

opengraph-image.js

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

export const contentType = "image/png";
 
export default function Image() {}

opengraph-image.js

export const contentType = "image/png";
 
export default function Image() {}

<head>

<meta property="og:image:type" content="image/png" />

路由段配置

opengraph-image 和 twitter-image 是专门的路由处理程序，可以使用与页面和布局相同的路由段配置选项。

示例

使用外部数据

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

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

app/posts/[slug]/opengraph-image.tsx

import { ImageResponse } from "next/og";
 
export const alt = "关于 Acme";
export const size = {
  width: 1200,
  height: 630,
};
export const contentType = "image/png";
 
export default async function Image({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://.../posts/${params.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 = "关于 Acme";
export const size = {
  width: 1200,
  height: 630,
};
export const contentType = "image/png";
 
export default async function Image({ params }) {
  const post = await fetch(`https://.../posts/${params.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,
    }
  );
}

使用 Edge 运行时和本地资源

这个示例使用 Edge 运行时从文件系统获取本地图片，并将其作为 ArrayBuffer 传递给 <img> 元素的 src 属性。本地资源应该放置在示例源文件位置的相对路径下。

app/opengraph-image.tsx

import { ImageResponse } from "next/og";
 
export const runtime = "edge";
 
export default async function Image() {
  const logoSrc = await fetch(new URL("./logo.png", import.meta.url)).then(
    (res) => res.arrayBuffer()
  );
 
  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";
 
export const runtime = "edge";
 
export default async function Image() {
  const logoSrc = await fetch(new URL("./logo.png", import.meta.url)).then(
    (res) => res.arrayBuffer()
  );
 
  return new ImageResponse(
    (
      <div
        style={{
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  );
}

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

这个示例使用 Node.js 运行时从文件系统获取本地图片，并将其作为 ArrayBuffer 传递给 <img> 元素的 src 属性。本地资源应该放置在项目根目录下，而不是示例源文件的位置。

app/opengraph-image.tsx

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",
        }}
      >
        <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";
 
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",
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  );
}

版本历史

版本	变更
`v13.3.0`	引入了 `opengraph-image` 和 `twitter-image`。