如何在 Next.js 中添加 Favicon(App Router 与 Pages Router)

Next.js 处理 favicon 的方式取决于你使用的是App Router(app/)还是Pages Router(pages/)。本指南会覆盖两者,以及让 Next.js 自动生成 <link> 标签的文件约定。

最快的方法:使用 Next.js 文件约定

在 App Router 中,Next.js 会自动检测 app/ 目录中的特殊文件名,并自动将正确的标签注入 <head>,无需任何代码。

将以下任意文件直接放在 app/ 中:

文件	作用
`favicon.ico`	经典的 `.ico` — 通用兜底
`icon.png` / `icon.svg`	现代图标;Next.js 会自动处理尺寸
`apple-icon.png`	iOS / Safari 触摸图标

app/
├── favicon.ico          # universal fallback
├── icon.png             # main icon (≥512×512)
├── icon.svg             # optional, crisp vector
├── apple-icon.png       # 180×180 for iOS
└── layout.tsx

就这样——无需手动编写 <link> 标签。Next.js 会在构建时输出正确的标记。

需要用一张图片生成所有这些文件? 将它上传到 Favicon.one,下载可直接放入 app/ 目录的完整包。

添加额外尺寸和 manifest

要实现完整的 PWA 配置(Android、启动画面、多种 PNG 尺寸),请生成这些文件并在 layout.tsx 中添加基于 metadata 的图标配置:

import type { Metadata } from 'next'

export const metadata: Metadata = {
  icons: {
    icon: [
      { url: '/favicon.ico', sizes: 'any' },
      { url: '/icon.svg', type: 'image/svg+xml' },
      { url: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' },
      { url: '/favicon-16x16.png', sizes: '16x16', type: 'image/png' },
    ],
    apple: ['/apple-touch-icon.png'],
  },
  manifest: '/site.webmanifest',
}

Pages Router(传统方式)

如果你使用的是 Pages Router,则没有自动检测的图标文件。把文件放到 public/ 中,并在 pages/_document.tsx 中添加标签:

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <link rel="icon" href="/favicon.ico" />
        <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
        <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
        <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
        <link rel="manifest" href="/site.webmanifest" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Next.js favicon 常见陷阱

1. favicon 在开发环境显示但在生产环境不显示

通常是构建缓存问题。删除 .next 并重新构建。同时确认文件确实被复制到了输出中——检查 .next/static 或你的部署产物。

2. 使用非正方形图片

Favicon 必须是正方形。先裁剪源图片,否则图标会显得拉伸变形。 Favicon.one 生成器会自动为你处理裁剪和缩放。

3. Next.js 缓存了旧的 favicon

Next.js 会对静态资源进行激进的哈希处理。更换 favicon 后,请执行完整重新构建和部署,并提醒用户强制刷新。

4. favicon 文件放错文件夹

App Router:文件放在 app/。Pages Router:文件放在 public/。把两者搞混是最常见的 Next.js favicon 错误。

验证是否生效

部署后,使用 Favicon Checker 审计你的网站——它会确认所有必需的图标和标签都已存在并被正确引用。

想要带有正确 Next.js 结构的完整 favicon 文件包? 在 Favicon.one 免费生成。