favicon、图标 和 Apple 图标

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

它们对于在网页浏览器标签页、手机主屏幕和搜索引擎结果等位置添加应用程序图标非常有用。

有两种方法可以设置应用程序图标：

使用图片文件（.ico, .jpg, .png）
使用代码生成图标（.js, .ts, .tsx）

图片文件（.ico, .jpg, .png）

通过将 favicon、icon 或 apple-icon 图片文件放置在您的 /app 目录中，使用图片文件来设置应用程序图标。
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" />

`icon`

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

html

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

`apple-icon`

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

html

<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 x 32 像素的 .png 文件将具有 type="image/png" 和 sizes="32x32" 属性。

当扩展名为 .svg 或文件图片大小未确定时，sizes="any" 会被添加到图标中。更多详细信息请参阅此 favicon handbook。

使用代码生成图标（.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'

// Image metadata
export const size = {
  width: 32,
  height: 32,
}
export const contentType = 'image/png'

// Image generation
export default function Icon() {
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 24,
          background: 'black',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
        }}
      >
        A
      </div>
    ),
    // ImageResponse options
    {
      // For convenience, we can re-use the exported icons size metadata
      // config to also set the ImageResponse's width and height.
      ...size,
    }
  )
}

jsx

import { ImageResponse } from 'next/og'

// Image metadata
export const size = {
  width: 32,
  height: 32,
}
export const contentType = 'image/png'

// Image generation
export default function Icon() {
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 24,
          background: 'black',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
        }}
      >
        A
      </div>
    ),
    // ImageResponse options
    {
      // For convenience, we can re-use the exported icons size metadata
      // config to also set the ImageResponse's width and height.
      ...size,
    }
  )
}

html

<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />

须知：

默认情况下，生成的图标是 静态优化 的（在构建时生成并缓存），除非它们使用动态 API 或未缓存的数据。

您可以使用 generateImageMetadata 在同一个文件中生成多个图标。

您不能生成 favicon 图标。请改用 icon 或 favicon.ico 文件。

应用程序图标是特殊的路由处理程序，默认情况下会被缓存，除非它们使用动态 API 或动态配置选项。

属性

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

`params`（可选）

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

须知：如果您使用 generateImageMetadata，该函数还将接收一个 id 属性，它是一个解析为 generateImageMetadata 返回的其中一个项目的 id 值的 Promise。

tsx

export default async function Icon({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}

jsx

export default async function Icon({ params }) {
  const { slug } = await params
  // ...
}

路由	URL	`params`
`app/shop/icon.js`	`/shop`	`undefined`
`app/shop/[slug]/icon.js`	`/shop/1`	`Promise<{ slug: '1' }>`
`app/shop/[tag]/[item]/icon.js`	`/shop/1/2`	`Promise<{ tag: '1', item: '2' }>`

返回值

须知：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() {}

jsx

export const size = { width: 32, height: 32 }

export default function Icon() {}

html

<link rel="icon" sizes="32x32" />

`contentType`

tsx

export const contentType = 'image/png'

export default function Icon() {}

jsx

export const contentType = 'image/png'

export default function Icon() {}

html

<link rel="icon" type="image/png" />

路由段配置

icon 和 apple-icon 是特殊的路由处理程序，它们可以使用与页面和布局相同的路由段配置选项。

版本历史

版本	变更
`v16.0.0`	`params` 现在是一个解析为对象的 promise
`v13.3.0`	引入了 `favicon`、`icon` 和 `apple-icon`

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

它们对于在网页浏览器标签页、手机主屏幕和搜索引擎结果等位置添加应用程序图标非常有用。

有两种方法可以设置应用程序图标：

使用图片文件（.ico, .jpg, .png）
使用代码生成图标（.js, .ts, .tsx）

图片文件（.ico, .jpg, .png）

通过将 favicon、icon 或 apple-icon 图片文件放置在您的 /app 目录中，使用图片文件来设置应用程序图标。
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" />

`icon`

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

html

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

`apple-icon`

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

html

<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 x 32 像素的 .png 文件将具有 type="image/png" 和 sizes="32x32" 属性。

当扩展名为 .svg 或文件图片大小未确定时，sizes="any" 会被添加到图标中。更多详细信息请参阅此 favicon handbook。

使用代码生成图标（.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'

// Image metadata
export const size = {
  width: 32,
  height: 32,
}
export const contentType = 'image/png'

// Image generation
export default function Icon() {
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 24,
          background: 'black',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
        }}
      >
        A
      </div>
    ),
    // ImageResponse options
    {
      // For convenience, we can re-use the exported icons size metadata
      // config to also set the ImageResponse's width and height.
      ...size,
    }
  )
}

jsx

import { ImageResponse } from 'next/og'

// Image metadata
export const size = {
  width: 32,
  height: 32,
}
export const contentType = 'image/png'

// Image generation
export default function Icon() {
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 24,
          background: 'black',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
        }}
      >
        A
      </div>
    ),
    // ImageResponse options
    {
      // For convenience, we can re-use the exported icons size metadata
      // config to also set the ImageResponse's width and height.
      ...size,
    }
  )
}

html

<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />

须知：

默认情况下，生成的图标是 静态优化 的（在构建时生成并缓存），除非它们使用动态 API 或未缓存的数据。

您可以使用 generateImageMetadata 在同一个文件中生成多个图标。

您不能生成 favicon 图标。请改用 icon 或 favicon.ico 文件。

应用程序图标是特殊的路由处理程序，默认情况下会被缓存，除非它们使用动态 API 或动态配置选项。

属性

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

`params`（可选）

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

须知：如果您使用 generateImageMetadata，该函数还将接收一个 id 属性，它是一个解析为 generateImageMetadata 返回的其中一个项目的 id 值的 Promise。

tsx

export default async function Icon({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}

jsx

export default async function Icon({ params }) {
  const { slug } = await params
  // ...
}

路由	URL	`params`
`app/shop/icon.js`	`/shop`	`undefined`
`app/shop/[slug]/icon.js`	`/shop/1`	`Promise<{ slug: '1' }>`
`app/shop/[tag]/[item]/icon.js`	`/shop/1/2`	`Promise<{ tag: '1', item: '2' }>`

返回值

须知：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() {}

jsx

export const size = { width: 32, height: 32 }

export default function Icon() {}

html

<link rel="icon" sizes="32x32" />

`contentType`

tsx

export const contentType = 'image/png'

export default function Icon() {}

jsx

export const contentType = 'image/png'

export default function Icon() {}

html

<link rel="icon" type="image/png" />

路由段配置

icon 和 apple-icon 是特殊的路由处理程序，它们可以使用与页面和布局相同的路由段配置选项。

版本历史

版本	变更
`v16.0.0`	`params` 现在是一个解析为对象的 promise
`v13.3.0`	引入了 `favicon`、`icon` 和 `apple-icon`

文档导航

图片文件（.ico, .jpg, .png）

favicon

icon

apple-icon

使用代码生成图标（.js, .ts, .tsx）

属性

params（可选）

返回值

配置导出

size

contentType

路由段配置

版本历史

图片文件（.ico, .jpg, .png）

favicon

icon

apple-icon

使用代码生成图标（.js, .ts, .tsx）

属性

params（可选）

返回值

配置导出

size

contentType

路由段配置

版本历史

`favicon`

`icon`

`apple-icon`

`params`（可选）

`size`

`contentType`

`favicon`

`icon`

`apple-icon`

`params`（可选）

`size`

`contentType`