favicon、icon 與 apple-icon

favicon、icon 或 apple-icon 檔案規範允許您為應用程式設定圖示。

這些圖示適用於新增出現在網頁瀏覽器分頁、手機主畫面及搜尋引擎結果等位置的應用程式圖示。

設定應用程式圖示有兩種方式：

使用圖片檔案 (.ico, .jpg, .png)
使用程式碼生成圖示 (.js, .ts, .tsx)

圖片檔案 (.ico, .jpg, .png)

透過在 /app 目錄中放置 favicon、icon 或 apple-icon 圖片檔案來設定應用程式圖示。favicon 圖片只能位於 app/ 的頂層目錄中。

Next.js 會評估檔案並自動將適當的標籤新增至應用程式的 <head> 元素。

檔案規範	支援的檔案類型	有效位置
`favicon`	`.ico`	`app/`
`icon`	`.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`	`app/*/`
`apple-icon`	`.jpg`, `.jpeg`, `.png`	`app/*/`

`favicon`

在根目錄 /app 路由區段新增 favicon.ico 圖片檔案。

<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.png、icon2.png 等。編號檔案會依詞法排序。

Favicon 只能在根目錄 /app 區段中設定。如果需要更細緻的設定，可以使用 icon。

適當的 <link> 標籤和屬性（如 rel、href、type 和 sizes）由圖示類型和評估檔案的元資料決定。

例如，32x32 像素的 .png 檔案會有 type="image/png" 和 sizes="32x32" 屬性。

sizes="any" 會新增至 favicon.ico 輸出，以避免瀏覽器錯誤，即 .ico 圖示優先於 .svg。

使用程式碼生成圖示 (.js, .ts, .tsx)

除了使用圖片檔案外，您還可以使用程式碼生成圖示。

透過建立預設匯出函式的 icon 或 apple-icon 路由來生成應用程式圖示。

檔案規範	支援的檔案類型
`icon`	`.js`, `.ts`, `.tsx`
`apple-icon`	`.js`, `.ts`, `.tsx`

生成圖示最簡單的方法是使用 next/og 中的 ImageResponse API。

import { ImageResponse } from 'next/og'

// 路由區段設定
export const runtime = 'edge'

// 圖片元資料
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,
    }
  )
}

import { ImageResponse } from 'next/og'

// 路由區段設定
export const runtime = 'edge'

// 圖片元資料
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> 輸出

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

須知事項

預設情況下，生成的圖示會進行靜態優化（在建置時生成並快取），除非它們使用動態函式或未快取的資料。

您可以使用 generateImageMetadata 在同一個檔案中生成多個圖示。

您無法生成 favicon 圖示。請改用 icon 或 favicon.ico 檔案。

屬性

預設匯出函式接收以下屬性：

`params` (選用)

包含從根區段到 icon 或 apple-icon 所在區段的動態路由參數物件。

export default function Icon({ params }: { params: { slug: string } }) {
  // ...
}

export default function Icon({ params }) {
  // ...
}

路由	URL	`params`
`app/shop/icon.js`	`/shop`	`undefined`
`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'] }`

回傳值

須知：ImageResponse 符合此回傳類型。

設定匯出

您可以選擇性地透過從 icon 或 apple-icon 路由匯出 size 和 contentType 變數來設定圖示的元資料。

選項	類型
`size`	`{ width: number; height: number }`
`contentType`	`string` - 圖片 MIME 類型

`size`

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

export default function Icon() {}

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

export default function Icon() {}

<head> 輸出

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

`contentType`

export const contentType = 'image/png'

export default function Icon() {}

export const contentType = 'image/png'

export default function Icon() {}

<head> 輸出

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

路由區段設定

icon 和 apple-icon 是專門的路由處理器，可以使用與頁面和佈局相同的路由區段設定選項。

選項	類型	預設值
`dynamic`	`'auto' \| 'force-dynamic' \| 'error' \| 'force-static'`	`'auto'`
`revalidate`	`false \| 'force-cache' \| 0 \| number`	`false`
`runtime`	`'nodejs' \| 'edge'`	`'nodejs'`
`preferredRegion`	`'auto' \| 'global' \| 'home' \| string \| string[]`	`'auto'`

export const runtime = 'edge'

export default function Icon() {}

export const runtime = 'edge'

export default function Icon() {}

版本歷史

版本	變更
`v13.3.0`	引入 `favicon`、`icon` 和 `apple-icon`

On this page