NNext.js 中文网 GitHub

favicon、icon 和 apple-icon

Favicon、Icon 和 Apple Icon 文件约定的 API 参考。

favicon、icon 或 apple-icon 文件约定允许你为应用设置图标。

它们可用于添加应用图标,这些图标会出现在浏览器标签页、手机主屏幕和搜索引擎结果等位置。

设置应用图标有两种方式:

图片文件(.ico、.jpg、.png)#

通过将 favicon、icon 或 apple-icon 图片文件放在 /app 目录中,可以使用图片文件设置应用图标。favicon 图片只能位于 app/ 的顶层。

Next.js 会计算该文件,并自动将相应的标签添加到应用的 <head> 元素中。

文件约定支持的文件类型有效位置
favicon.icoapp/
icon.ico、.jpg、.jpeg、.png、.svgapp/**/*
apple-icon.jpg、.jpeg、.pngapp/**/*

favicon#

将 favicon.ico 图片文件添加到根 /app 路由片段中。

<head> output
<link rel="icon" href="/favicon.ico" sizes="any" />

icon#

添加一个 icon.(ico|jpg|jpeg|png|svg) 图片文件。

<head> output
<link
  rel="icon"
  href="/icon?<generated>"
  type="image/<generated>"
  sizes="<generated>"
/>

apple-icon#

添加一个 apple-icon.(jpg|jpeg|png) 图片文件。

<head> output
<link
  rel="apple-touch-icon"
  href="/apple-icon?<generated>"
  type="image/<generated>"
  sizes="<generated>"
/>

小知识:

  • 你可以通过在文件名后添加数字后缀来设置多个图标。例如 icon1.png、icon2.png 等。带编号的文件将按字典序排序。
  • Favicon 只能在根 /app 片段中设置。如果需要更细粒度的控制,可以使用 icon。
  • 相应的 <link> 标签以及 rel、href、type 和 sizes 等属性由图标类型和所计算文件的元数据决定。
  • 例如,一个 32×32 像素的 .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。

app/icon.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,
    }
  )
}
app/icon.js
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,
    }
  )
}
<head> output
<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />

小知识:

属性#

默认导出的函数接收以下属性:

params(可选)#

一个 Promise,解析为一个对象,其中包含从根片段到 icon 或 apple-icon 所在片段的动态路由参数对象。

小知识:如果你使用了 generateImageMetadata,该函数还会接收一个 id 属性,它是一个 Promise,解析为 generateImageMetadata 返回的某一项中的 id 值。

app/shop/[slug]/icon.tsx
export default async function Icon({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}
app/shop/[slug]/icon.js
export default async function Icon({ params }) {
  const { slug } = await params
  // ...
}
路由URLparams
app/shop/icon.js/shopundefined
app/shop/[slug]/icon.js/shop/1Promise<{ slug: '1' }>
app/shop/[tag]/[item]/icon.js/shop/1/2Promise<{ tag: '1', item: '2' }>

返回值#

默认导出的函数应返回 Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response。

小知识:ImageResponse 满足此返回类型。

配置导出#

你可以选择通过从 icon 或 apple-icon 路由导出 size 和 contentType 变量来配置图标的元数据。

选项类型
size{ width: number; height: number }
contentTypestring - 图片 MIME 类型

size#

icon.tsx | apple-icon.tsx
export const size = { width: 32, height: 32 }

export default function Icon() {}
icon.js | apple-icon.js
export const size = { width: 32, height: 32 }

export default function Icon() {}
<head> output
<link rel="icon" sizes="32x32" />

contentType#

icon.tsx | apple-icon.tsx
export const contentType = 'image/png'

export default function Icon() {}
icon.js | apple-icon.js
export const contentType = 'image/png'

export default function Icon() {}
<head> output
<link rel="icon" type="image/png" />

路由片段配置#

icon 和 apple-icon 是特殊的 Route Handlers,可以使用与 Pages 和 Layouts 相同的路由片段配置选项。

故障排除#

在 catch-all 片段中使用图标#

icon 和 apple-icon 文件不能放置在 catch-all([...slug])或可选 catch-all([[...slug]])片段内。catch-all 片段必须是路由的最后一个片段,因此像 /docs/[...slug]/icon 这样的图标路由永远无法被匹配。Next.js 会针对这些文件报错。

相反,请将图标放在 catch-all 片段之外的父片段中,或者通过 Route Handler 提供图标,并在 generateMetadata 的 icons 字段中引用它。opengraph-image 文档展示了 Open Graph 图片的相同模式。

版本历史#

VersionChanges
v16.0.0params 现在是一个解析为对象的 Promise
v13.3.0引入 favicon、icon 和 apple-icon
Next.js 中文网