跳到內容
檔案系統約定元資料檔案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 已引入