opengraph-image 和 twitter-image 文件约定允许您为路由段设置 Open Graph 和 Twitter 图像。
当用户分享您网站的链接时，它们有助于设置在社交网络和消息应用上显示的图像。
有两种方法可以设置 Open Graph 和 Twitter 图像：
通过在路由段中放置一个 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 文件作为其替代文本。
About Acme<meta property="og:image:alt" content="About Acme" />twitter-image.alt.txt在与 twitter-image.(jpg|jpeg|png|gif) 图像相同的路由段中添加一个配套的 twitter-image.alt.txt 文件作为其替代文本。
About Acme<meta property="twitter:image:alt" content="About Acme" />除了使用 实际图像文件 外，您还可以通过代码以编程方式生成图像。
通过创建默认导出函数的 opengraph-image 或 twitter-image 路由，来生成路由段的共享图像。
| 文件约定 | 支持的文件类型 |
|---|---|
opengraph-image | .js, .ts, .tsx |
twitter-image | .js, .ts, .tsx |
须知:
- 默认情况下，生成的图像会进行 静态优化（在构建时生成并缓存），除非它们使用 动态 API 或未缓存的数据。
- 您可以使用
generateImageMetadata在同一个文件中生成多个图像。opengraph-image.js和twitter-image.js是特殊的路由处理程序，默认情况下会进行缓存，除非它们使用 动态 API 或 动态配置 选项。
生成图像最简单的方法是使用 next/og 中的 ImageResponse API。
import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
// Image metadata
export const alt = 'About Acme'
export const size = {
width: 1200,
height: 630,
}
export const contentType = 'image/png'
// Image generation
export default async function Image() {
// Font loading, process.cwd() is Next.js project directory
const interSemiBold = await readFile(
join(process.cwd(), 'assets/Inter-SemiBold.ttf')
)
return new ImageResponse(
(
// ImageResponse JSX element
<div
style={{
fontSize: 128,
background: 'white',
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
}}
>
About Acme
</div>
),
// ImageResponse options
{
// For convenience, we can re-use the exported opengraph-image
// size config to also set the ImageResponse's width and 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'
// Image metadata
export const alt = 'About Acme'
export const size = {
width: 1200,
height: 630,
}
export const contentType = 'image/png'
// Image generation
export default async function Image() {
// Font loading, process.cwd() is Next.js project directory
const interSemiBold = await readFile(
join(process.cwd(), 'assets/Inter-SemiBold.ttf')
)
return new ImageResponse(
(
// ImageResponse JSX element
<div
style={{
fontSize: 128,
background: 'white',
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
}}
>
About Acme
</div>
),
// ImageResponse options
{
// For convenience, we can re-use the exported opengraph-image
// size config to also set the ImageResponse's width and 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" />默认导出的函数接收以下 props：
params (可选)一个 Promise，解析为一个对象，该对象包含从根路由段到 opengraph-image 或 twitter-image 所在的路由段的 动态路由参数。
须知: 如果您使用
generateImageMetadata，该函数还将接收一个idprop，它是一个 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' }> |
默认导出的函数应返回 Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response。
须知:
ImageResponse满足此返回类型。
您可以通过从 opengraph-image 或 twitter-image 路由中导出 alt、size 和 contentType 变量来可选地配置图像的元数据。
| 选项 | 类型 |
|---|---|
alt | string |
size | { width: number; height: number } |
contentType | string - image MIME type |
altexport 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" />sizeexport 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" />contentTypeexport 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 是专门的 路由处理程序，它们可以使用与页面和布局相同的 路由段配置 选项。
此示例使用 params 对象和外部数据来生成图像。
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 运行时从文件系统获取本地图像，并将其作为 base64 字符串或 ArrayBuffer 传递给 <img> 的 src 属性。请将本地资产放置在项目根目录的相对位置，而不是示例源文件的相对位置。
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>
)
)
}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 指令或类似方法来使用此 功能。
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 accepts ArrayBuffer/typed arrays for <img src> at runtime */}
<img src={logoSrc} height="100" />
</div>
)
)
}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>
)
)
}| 版本 | 更改 |
|---|---|
v16.0.0 | params 现在是一个解析为对象的 Promise |
v13.3.0 | 引入了 opengraph-image 和 twitter-image。 |