NextJS中文文档 - Opengraph 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)
图像文件。
html
<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>" />
1
2
3
4
2
3
4
twitter-image
在任何路由段中添加 twitter-image.(jpg|jpeg|png|gif)
图像文件。
html
<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>" />
1
2
3
4
2
3
4
opengraph-image.alt.txt
在与 opengraph-image.(jpg|jpeg|png|gif)
图像相同的路由段中添加 opengraph-image.alt.txt
文件作为其替代文本。
txt
About Acme
1
html
<meta property="og:image:alt" content="About Acme" />
1
twitter-image.alt.txt
在与 twitter-image.(jpg|jpeg|png|gif)
图像相同的路由段中添加 twitter-image.alt.txt
文件作为其替代文本。
txt
About Acme
1
html
<meta property="twitter:image:alt" content="About Acme" />
1
使用代码生成图像 (.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
是默认被缓存的特殊路由处理程序,除非它们使用了动态 API或动态配置选项。
生成图像最简单的方法是使用 next/og
中的 ImageResponse API。
tsx
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
// 尺寸配置来设置 ImageResponse 的宽度和高度。
...size,
fonts: [
{
name: 'Inter',
data: interSemiBold,
style: 'normal',
weight: 400,
},
],
},
)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
jsx
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
// 尺寸配置来设置 ImageResponse 的宽度和高度。
...size,
fonts: [
{
name: 'Inter',
data: interSemiBold,
style: 'normal',
weight: 400,
},
],
},
)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
html
<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" />
1
2
3
4
5
2
3
4
5
Props
默认导出函数接收以下 props:
params
(可选)
一个包含从根段到 opengraph-image
或 twitter-image
所在段的动态路由参数对象。
tsx
export default function Image({ params }: { params: { slug: string } }) {
// ...
}
1
2
3
2
3
jsx
export default function Image({ params }) {
// ...
}
1
2
3
2
3
路由 | 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' } |
返回值
默认导出函数应返回 Blob
| ArrayBuffer
| TypedArray
| DataView
| ReadableStream
| Response
。
须知:
ImageResponse
满足此返回类型。
配置导出
你可以通过从 opengraph-image
或 twitter-image
路由导出 alt
、size
和 contentType
变量来选择性地配置图像的元数据。
选项 | 类型 |
---|---|
alt | string |
size | { width: number; height: number } |
contentType | string - 图像 MIME 类型 |
alt
tsx
export const alt = 'My images alt text'
export default function Image() {}
1
2
3
2
3
jsx
export const alt = 'My images alt text'
export default function Image() {}
1
2
3
2
3
html
<meta property="og:image:alt" content="My images alt text" />
1
size
tsx
export const size = { width: 1200, height: 630 }
export default function Image() {}
1
2
3
2
3
jsx
export const size = { width: 1200, height: 630 }
export default function Image() {}
1
2
3
2
3
html
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
1
2
2
contentType
tsx
export const contentType = 'image/png'
export default function Image() {}
1
2
3
2
3
jsx
export const contentType = 'image/png'
export default function Image() {}
1
2
3
2
3
html
<meta property="og:image:type" content="image/png" />
1
路由段配置
opengraph-image
和 twitter-image
是专门的路由处理程序,可以使用与页面和布局相同的路由段配置选项。
示例
使用外部数据
此示例使用 params
对象和外部数据生成图像。
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: { 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,
},
)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
jsx
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 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,
},
)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
使用 Node.js 运行时和本地资源
此示例使用 Node.js 运行时从文件系统获取本地图像,并将其作为 ArrayBuffer
传递给 <img>
元素的 src
属性。本地资源应放置在项目根目录下,而不是示例源文件的位置。
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>
),
)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
jsx
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>
),
)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
版本历史
版本 | 变更 |
---|---|
v13.3.0 | 引入 opengraph-image 和 twitter-image 。 |