快速在 Next.js App Router 中添加 Favicon

如果你打开使用 App Router 的 Next.js 站点时只看到一个通用的浏览器标签图标，通常是因为 metadata 配置不完整导致 favicon 缺失。

前置条件

• 使用 app 目录的 Next.js 13+ 项目。
• 本地已安装 Node.js 18 及以上。
• 使用 Mzu favicondl 生成的图标集合（SVG、PNG、ICO）。favicon 尺寸指南可帮助挑选合适的尺寸。

逐步实现

1. 生成图标文件。 使用 Mzu favicondl 创建至少三个文件：
   • favicon.svg – 推荐的可伸缩矢量格式。
   • favicon.ico – 为仍然请求 /favicon.ico 的旧浏览器提供的回退。
   • apple-touch-icon.png – 可选的 Apple Touch 图标。
   将这些文件保存到项目的 public 目录。
2. 在 app/layout.tsx 中导出 metadata。 App Router 会读取布局文件中的 metadata 导出。添加一个 icons 对象并指向刚才放置的文件。

   <pre><code>export const metadata = {
     title: 'My Next.js Site',
     icons: {
       icon: '/favicon.ico', // legacy fallback
       shortcut: '/favicon.ico', // shortcut icon for older browsers
       apple: '/apple-touch-icon.png', // Apple Touch icon (optional)
       other: [
         { rel: 'icon', url: '/favicon.svg', type: 'image/svg+xml', sizes: 'any' }
       ]
     }
   };
   </code></pre>

   这符合 Next.js 官方文档中基于文件的 metadata 写法。
3. 检查生成的 <head> 输出。 运行 npm run dev 并打开页面源码。你应该能看到类似以下的 link 标签：

   <link rel='icon' href='/favicon.ico'>
   <link rel='shortcut icon' href='/favicon.ico'>
   <link rel='apple-touch-icon' href='/apple-touch-icon.png'>
   <link rel='icon' href='/favicon.svg' type='image/svg+xml' sizes='any'>

   这些标签由框架自动生成，无需手动编写。
4. 在多个浏览器中测试。 在 Chrome、Safari 和 Firefox 中打开站点。高 DPI 屏幕应显示 SVG 图标，旧版浏览器则回退到 ICO 文件。
   • Chrome 在存在 type='image/svg+xml' 时会优先使用 SVG。
   • Safari 会使用 Apple Touch 图标作为首页快捷方式。
   • Firefox 会遵循 rel='icon' 条目，如果缺少 SVG 则缓存 ICO 文件。
5. 部署。 将修改推送到你的托管平台（Vercel、Netlify 等）。public 文件夹是静态提供的，构建完成后图标即可立即生效。

常见坑点

• 缺少 public 文件夹路径。 若图标放在 public 之外，生成的 URL 会指向不存在的位置，浏览器会报 404 错误。
• 仅使用 rel='shortcut icon'。 现代浏览器遵循 rel='icon' 规范（HTML spec）。只依赖旧属性会导致 SVG 被忽略。
• 缓存导致的旧图标。 浏览器会强力缓存 favicon.ico。可以在 URL 后追加查询字符串（如 /favicon.ico?v=2）或在构建时启用内容哈希以强制更新。
• MIME 类型不正确。 .svg 必须以 image/svg+xml 响应，.ico 必须以 image/x-icon 响应。服务器配置错误会导致浏览器拒绝加载。

结论

让 App Router 通过单一的 metadata 导出自动生成 <link> 标签，可保持 favicon 配置声明式且具备未来兼容性。上述步骤涵盖了图标生成、放置、metadata 导出、验证以及部署，帮助你在几分钟内从空白标签图标升级为完整的品牌标识。

需要快速生成 SVG 与 ICO 文件？试试 Mzu favicondl——它会输出符合 App Router 需求的完整文件集。

查看官方要求

Next.js 在其 metadata file conventions 中对 favicons 与 app icons 进行了说明。