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) 图片文件添加到任意路由段中。
<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) 图片文件添加到任意路由段中。
<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 文本。
About Acme<meta property="og:image:alt" content="About Acme" />twitter-image.alt.txt#
在与 twitter-image.(jpg|jpeg|png|gif) 图片相同的路由段中添加一个配套的 twitter-image.alt.txt 文件,作为其 alt 文本。
About Acme<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。
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,
},
],
}
)
}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,
},
],
}
)
}<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值。
export default async function Image({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// ...
}export default async function Image({ params }) {
const { slug } = await params
// ...
}| 路由 | URL | params |
|---|---|---|
app/shop/opengraph-image.js | /shop | undefined |
app/shop/[slug]/opengraph-image.js | /shop/1 | Promise<{ slug: '1' }> |
app/shop/[tag]/[item]/opengraph-image.js | /shop/1/2 | Promise<{ tag: '1', item: '2' }> |
返回值#
默认导出的函数应返回一个 Response。
小知识:
ImageResponse满足此返回类型。
配置导出#
你可以选择通过从 opengraph-image 或 twitter-image 路由导出 alt、size 和 contentType 变量来配置图片的 metadata。
| 选项 | 类型 |
|---|---|
alt | string |
size | { width: number; height: number } |
contentType | string - 图片 MIME 类型 |
alt#
export const alt = 'My images alt text'
export default function Image() {}export const alt = 'My images alt text'
export default function Image() {}<meta property="og:image:alt" content="My images alt text" />size#
export const size = { width: 1200, height: 630 }
export default function Image() {}export const size = { width: 1200, height: 630 }
export default function Image() {}<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />contentType#
export const contentType = 'image/png'
export default function Image() {}export const contentType = 'image/png'
export default function Image() {}<meta property="og:image:type" content="image/png" />路由段配置#
opengraph-image 和 twitter-image 是特殊的 Route Handlers,可以使用与 Pages 和 Layouts 相同的路由段配置选项。
示例#
使用外部数据#
此示例使用 params 对象和外部数据来生成图片。
小知识: 默认情况下,生成的图片将进行静态优化。你可以配置单个
fetch的options或路由段的选项来更改此行为。
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,
}
)
}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。请将本地资源相对于项目根目录放置,而不是相对于示例源文件。
该资源不依赖请求数据,因此在模块作用域中读取一次即可。请参阅可预测的值。
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>
)
)
}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 指令或类似方式来使用此功能。
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>
)
)
}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 文件不同:
- 检查页面渲染的
og:image或twitter:imagemeta 标签,以找到所选图片的 URL。即使页面的 metadata 指向别处,基于文件的图片路由仍可能提供图片。 - 检查页面的 metadata 导出中是否有
openGraph.images或twitter.images,包括从共享对象复制的属性。 - 完全省略相应的
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 中引用它:
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 }
)
}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 }
)
}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] },
}
}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.0 | params 现在是一个解析为对象的 promise |
v13.3.0 | 引入了 opengraph-image 和 twitter-image。 |