next.js 中文文档

主题

Favicon、图标和苹果图标 ​

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

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

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

图像文件 (.ico, .jpg, .png) ​

通过在 /app 目录内放置 favicon、icon 或 apple-icon 图像文件来设置应用程序图标。 favicon 图像只能位于 app/ 的顶级。

Next.js 将评估该文件，并自动向您的应用程序的 <head> 元素添加适当的标签。

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

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 乘 32 像素的 .png 文件将具有 type="image/png" 和 sizes="32x32" 属性。
  • 在 favicon.ico 输出中添加 sizes="any" 是为了避免浏览器错误，其中 .ico 图标优先于 .svg。

使用代码生成图标 (.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,
    }
  )
}
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,
    }
  )
}
html
<link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />

须知

Props ​

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

params（可选） ​

包含从根段到icon或apple-icon共位的动态路由参数对象的params对象。

tsx
export default function Icon({ params }: { params: { slug: string } }) {
  // ...
}
jsx
export default function Icon({ params }) {
  // ...
}
路由URLparams
app/shop/icon.js/shopundefined
app/shop/[slug]/icon.js/shop/1{ slug: '1' }
app/shop/[tag]/[item]/icon.js/shop/1/2{ tag: '1', item: '2' }
app/shop/[...slug]/icon.js/shop/1/2{ slug: ['1', '2'] }

返回值 ​

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

须知：ImageResponse 满足此返回类型。

配置导出 ​

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

选项类型
size{ width: number; height: number }
contentTypestring - 图片 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 是专门的 路由处理器，可以使用与页面和布局相同的 路由段配置 选项。

版本历史 ​

版本变更
v13.3.0引入 favicon icon 和 apple-icon