跳到内容
文件系统约定元数据文件favicon、icon 和 apple-icon

favicon, icon 和 apple-icon

faviconiconapple-icon 文件约定允许您为应用程序设置图标。

它们对于添加应用程序图标很有用,这些图标会出现在网络浏览器标签页、手机主屏幕和搜索引擎结果等地方。

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

图像文件(.ico、.jpg、.png)

通过将 faviconiconapple-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> 输出
<link rel="icon" href="/favicon.ico" sizes="any" />

icon

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

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

apple-icon

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

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

须知:

  • 您可以通过在文件名后添加数字后缀来设置多个图标。例如,icon1.pngicon2.png 等。带编号的文件将按字典顺序排序。
  • Favicon 只能设置在根 /app 段中。如果您需要更精细的控制,可以使用 icon
  • 适当的 <link> 标签和属性,例如 relhreftypesizes,由评估文件的图标类型和元数据决定。
  • 例如,一个 32x32px 的 .png 文件将具有 type="image/png"sizes="32x32" 属性。
  • 当扩展名为 .svg 或无法确定图像文件大小时,图标会添加 sizes="any"。更多详细信息请参阅此 favicon 手册

使用代码生成图标(.js、.ts、.tsx)

除了使用 文字图像文件,您还可以使用代码程序化地**生成**图标。

通过创建默认导出函数的 iconapple-icon 路由来生成应用程序图标。

文件约定支持的文件类型
icon.js, .ts, .tsx
apple-icon.js, .ts, .tsx

生成图标最简单的方法是使用 next/og 中的 ImageResponse API。

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

须知:

  • 默认情况下,生成的图标是**静态优化**的(在构建时生成并缓存),除非它们使用动态 API 或未缓存的数据。
  • 您可以使用 generateImageMetadata 在同一个文件中生成多个图标。
  • 您不能生成 favicon 图标。请改用 iconfavicon.ico 文件。
  • 应用程序图标是特殊的路由处理程序,默认情况下会缓存,除非它们使用 动态 API动态配置 选项。

属性

默认导出函数接收以下 props

params (可选)

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

温馨提示:如果您使用 generateImageMetadata,该函数还将接收一个 id prop,它是一个 Promise,解析为 generateImageMetadata 返回的项目之一的 id 值。

app/shop/[slug]/icon.tsx
export default async function Icon({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  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 满足此返回类型。

配置导出

您可以选择通过从 iconapple-icon 路由导出 sizecontentType 变量来配置图标的元数据。

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

size

icon.tsx | apple-icon.tsx
export const size = { width: 32, height: 32 }
 
export default function Icon() {}
<head> 输出
<link rel="icon" sizes="32x32" />

contentType

icon.tsx | apple-icon.tsx
export const contentType = 'image/png'
 
export default function Icon() {}
<head> 输出
<link rel="icon" type="image/png" />

路由段配置

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

版本历史

版本更改
v16.0.0params 现在是一个解析为对象的 Promise
v13.3.0favicon iconapple-icon 已引入