NextJS中文文档 - App Icons
favicon、icon 或 apple-icon 文件约定允许你为应用程序设置图标。
这些图标在网络浏览器标签页、手机主屏幕和搜索引擎结果等场所显示，非常有用。
设置应用图标有两种方式：
图像文件 (.ico, .jpg, .png)
通过在 /app 目录中放置 favicon、icon 或 apple-icon 图像文件来设置应用图标。 favicon 图像只能位于 app/ 的顶层。
Next.js 将评估文件并自动将适当的标签添加到应用的 <head> 元素中。
| 文件约定 | 支持的文件类型 | 有效位置 |
|---|---|---|
favicon | .ico | app/ |
icon | .ico, .jpg, .jpeg, .png, .svg | app/**/* |
apple-icon | .jpg, .jpeg, .png | app/**/* |
favicon
将 favicon.ico 图像文件添加到根 /app 路由段。
html
<link rel="icon" href="/favicon.ico" sizes="any" />1
icon
添加 icon.(ico|jpg|jpeg|png|svg) 图像文件。
html
<link rel="icon" href="/icon?<generated>" type="image/<generated>" sizes="<generated>" />1
apple-icon
添加 apple-icon.(jpg|jpeg|png) 图像文件。
html
<link
rel="apple-touch-icon"
href="/apple-icon?<generated>"
type="image/<generated>"
sizes="<generated>"
/>1
2
3
4
5
6
2
3
4
5
6
须知：
- 你可以通过在文件名中添加数字后缀来设置多个图标。例如，
icon1.png、icon2.png等。带编号的文件将按字典顺序排序。- Favicon 只能在根
/app段中设置。如果你需要更精细的控制，可以使用icon。- 根据图标类型和评估文件的元数据，会自动确定适当的
<link>标签和属性，如rel、href、type和sizes。- 例如，一个 32x32 像素的
.png文件将具有type="image/png"和sizes="32x32"属性。- 当扩展名为
.svg或无法确定文件的图像大小时，会添加sizes="any"。更多详情请参阅这个 favicon 手册。
使用代码生成图标 (.js, .ts, .tsx)
除了使用实际图像文件外，你还可以使用代码以编程方式生成图标。
通过创建默认导出函数的 icon 或 apple-icon 路由来生成应用图标。
| 文件约定 | 支持的文件类型 |
|---|---|
icon | .js, .ts, .tsx |
apple-icon | .js, .ts, .tsx |
生成图标最简单的方法是使用 next/og 中的 ImageResponse API。
tsx
import { ImageResponse } from 'next/og'
// 图像元数据
export const size = {
width: 32,
height: 32,
}
export const contentType = 'image/png'
// 图像生成
export default function Icon() {
return new ImageResponse(
(
// ImageResponse JSX 元素
<div
style={{
fontSize: 24,
background: 'black',
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
color: 'white',
}}
>
A
</div>
),
// ImageResponse 选项
{
// 为方便起见，我们可以重用导出的图标尺寸元数据
// 配置来设置 ImageResponse 的宽度和高度。
...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
34
35
36
37
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
jsx
import { ImageResponse } from 'next/og'
// 图像元数据
export const size = {
width: 32,
height: 32,
}
export const contentType = 'image/png'
// 图像生成
export default function Icon() {
return new ImageResponse(
(
// ImageResponse JSX 元素
<div
style={{
fontSize: 24,
background: 'black',
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
color: 'white',
}}
>
A
</div>
),
// ImageResponse 选项
{
// 为方便起见，我们可以重用导出的图标尺寸元数据
// 配置来设置 ImageResponse 的宽度和高度。
...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
34
35
36
37
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
html
<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />1
须知：
- 默认情况下，生成的图标会进行静态优化（在构建时生成并缓存），除非它们使用动态 API或未缓存的数据。
- 你可以使用
generateImageMetadata在同一文件中生成多个图标。- 你不能生成
favicon图标。请使用icon或 favicon.ico 文件。- 应用图标是默认被缓存的特殊路由处理程序，除非它使用了动态 API或动态配置选项。
Props
默认导出函数接收以下 props：
params（可选）
一个包含从根段到 icon 或 apple-icon 所在段的动态路由参数对象。
tsx
export default function Icon({ params }: { params: { slug: string } }) {
// ...
}1
2
3
2
3
jsx
export default function Icon({ params }) {
// ...
}1
2
3
2
3
| 路由 | URL | params |
|---|---|---|
app/shop/icon.js | /shop | undefined |
app/shop/[slug]/icon.js | /shop/1 | { slug: '1' } |
app/shop/[tag]/[item]/icon.js | /shop/1/2 | { tag: '1', item: '2' } |
返回值
默认导出函数应返回 Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response。
须知：
ImageResponse满足此返回类型。
配置导出
你可以通过从 icon 或 apple-icon 路由导出 size 和 contentType 变量来选择性地配置图标的元数据。
| 选项 | 类型 |
|---|---|
size | { width: number; height: number } |
contentType | string - 图像 MIME 类型 |
size
tsx
export const size = { width: 32, height: 32 }
export default function Icon() {}1
2
3
2
3
jsx
export const size = { width: 32, height: 32 }
export default function Icon() {}1
2
3
2
3
html
<link rel="icon" sizes="32x32" />1
contentType
tsx
export const contentType = 'image/png'
export default function Icon() {}1
2
3
2
3
jsx
export const contentType = 'image/png'
export default function Icon() {}1
2
3
2
3
html
<link rel="icon" type="image/png" />1
路由段配置
icon 和 apple-icon 是专门的路由处理程序，可以使用与页面和布局相同的路由段配置选项。
版本历史
| 版本 | 变更 |
|---|---|
v13.3.0 | 引入 favicon、icon 和 apple-icon |
