Next.js 的网站图标
Next.js 14+ App Router 引入了基于文件的图标约定：将 favicon.ico 或 icon.png 放入 /app 目录中，Next.js 自动发出正确的 `<link>` 标签 - 无需手动 Head 组件。对于 Pages Router 项目，将 favicon.ico 放置在 /public 中并从 _document.tsx 链接它。 favicon generator 从一个源图像生成完整的文件集，best favicon size guide 涵盖了每个上下文的重要大小。
Next.js 13+ 和 App Router 将 /app 目录中的特殊文件名视为元数据约定。 Next.js 元数据系统会自动识别名为 favicon.ico、icon.png、icon.svg 和 apple-icon.png 的文件，并使用正确的响应标头和 `<link>` 标签提供服务，而无需在 layout.tsx 或元数据导出中进行任何配置。
要使用文件约定，请将 favicon.ico 放入 /app 目录（而不是 /public）中。 Next.js 在 /favicon.ico 路由上提供服务，并将链接标签注入到共享该布局的每个页面中。图标文件必须与根布局.tsx 处于同一级别，才能全局应用。
对于使用 App Router 的高 DPI 图标，请将 icon.png 放置在 /app 内。 Next.js 读取其尺寸并生成适当的“<link rel='icon' sizes='...' href='...'>”标签。要提供多种尺寸，请导出具有不同数字后缀的多个图标文件：icon.png (32×32)、icon@2x.png (64×64)，或使用 icon.svg 作为单个无限可扩展文件。
App Router 还支持 iOS 主屏幕图标的专用 apple-icon.png 文件。将 apple-icon.png (180×180) 放入 /app 中，Next.js 会自动发出 `<link rel='apple-touch-icon' href='...'>`。这是最简洁的方法——无需手动导出元数据。
如果您更喜欢在代码中而不是通过文件约定声明网站图标，请从layout.tsx 导出元数据对象。 Icons 属性接受带有快捷方式、图标、苹果和其他字段的对象。示例：“导出 const 元数据：元数据 = { icon: { icon: '/favicon.ico', apple: '/apple-touch-icon.png' } }`。当您需要基于区域设置或环境的动态图标路径时，此方法非常有用。
对于 Pages Router 项目（Next.js 12 及更低版本，或尚未迁移到 App Router 的项目），favicon 处理工作方式有所不同。将 favicon.ico 放在 /public 目录中 — Next.js 在根 URL 处为 /public 提供服务。在`<Head>`组件内的pages/_document.tsx中添加链接标签：`<link rel='icon' href='/favicon.ico' />`。这个`<Head>`是文档级的head，而不是每页的next/head导入。
next/head 组件（从“next/head”导入 Head）适用于 Pages Router 中的每页图标覆盖。如果您想在特定页面上使用不同的图标，请在该页面组件的 `<Head>` 内包含“<link rel='icon'>”。每页标签会覆盖文档级标签。这对于通过一个 Next.js 部署提供服务的多品牌站点非常有用。
Next.js App Router 约定完全支持 SVG 网站图标。将文件命名为 icon.svg 并将其放置在 /app 中。 Next.js 发出“<link rel='icon' type='image/svg+xml' href='/_next/static/media/icon.svg...'>”。由于 Next.js 对静态文件名进行哈希处理以进行缓存清除，因此您无需担心图标缓存失效 - 更改文件会更改哈希值并强制浏览器重新获取。
Next.js App Router 中的 Web 清单是通过 /app 中的 manifest.ts 文件配置的。导出返回包含图标大小的 MetadataRoute.Manifest 对象的默认函数。 Next.js 将其呈现为 /manifest.webmanifest 中的 application/manifest+json。清单中引用的 192×192 和 512×512 PNG 应放置在 /public 中。
Turbopack（Next.js 14+ 中的实验性捆绑器）以与 webpack 相同的方式处理 /public 中的静态资源。 /public 中的网站图标文件不捆绑提供。对于 /app（图标约定）中的文件，Turbopack 将它们作为元数据资产进行处理 - 在 Turbopack 和 webpack 之间切换时无需更改配置。
Next.js ISR（增量静态再生）和边缘部署不会影响网站图标服务。 Favicon 文件是由 CDN 边缘提供的静态资源，而不是来自 ISR 缓存。这意味着网站图标更新会在部署后立即传播，而无需等待页面重新验证。
多区域设置 Next.js 应用程序通常需要区域设置感知图标。使用layout.tsx 中的generateMetadata 函数根据params 对象返回特定于区域设置的图标路径。这是仅 App Router 的功能 - Pages Router 站点需要自定义 _document.tsx 逻辑或自定义服务器来实现每个区域设置的图标。
部署后，使用 favicon tester 验证您的 Next.js 网站图标。检查 /favicon.ico、/icon.svg 和 /apple-touch-icon.png 是否都返回具有正确内容类型标头的 200 个响应。另请检查已部署站点的“<head>”HTML，以确认 Next.js 发出了所有预期的链接标记。
工作原理
- 1
生成您的网站图标包
将 512×512 PNG 或 SVG 上传到 [favicon generator](tool:favicon-generator)。下载 favicon.ico、icon.svg、apple-touch-icon.png (180×180) 和清单 PNG。
- 2
将 favicon.ico 放入 /app (App Router)
将 favicon.ico 与 layout.tsx 一起复制到项目的 /app 目录中。 Next.js 自动为其提供服务并注入链接标签。对于 Pages Router，请将其放入 /public。
- 3
添加 icon.svg 以获得清晰的渲染
将 SVG 重命名为 icon.svg 并将其放置在 /app (App Router) 中。 Next.js 自动发出 SVG 链接标签。对于 Pages Router，放置在 /public 中并在 _document.tsx 中添加链接标签。
- 4
为 iOS 安装添加 apple-icon.png
将 180×180 PNG 重命名为 apple-icon.png 并将其放置在 /app (App Router) 中。对于 Pages Router，将 apple-touch-icon.png 放在 /public 中，并在 _document.tsx 中添加链接标签。
- 5
配置网络清单
对于 App Router，创建 /app/manifest.ts 并导出 Manifest 元数据，包括 192×192 和 512×512 图标条目。将 PNG 放入 /public 中。对于 Pages Router，将 site.webmanifest 放入 /public 中，并在 _document.tsx 中添加清单链接标签。
- 6
生产验证
部署后，查看实时 URL 上的源代码并确认所有链接标签都存在。使用 [favicon tester](utility:favicon-tester) 检查每个图标 URL 返回 200 以及正确的内容类型。
立即尝试
生成 Next.js 就绪的图标
Favicon 生成器常见问题
Next.js App Router 中的图标在哪里？+
/app 目录内。名为 favicon.ico、icon.png、icon.svg 和 apple-icon.png 的文件会自动识别并链接。全局图标出现在 /app 中；布局特定的目录位于相应的布局子目录中。
网站图标在 Next.js Pages Router 中的位置在哪里？+
在 /public 目录中。在`<Head>`组件内的pages/_document.tsx中添加链接标签。 Next.js 在根 URL 处提供 /public 文件 - /public/favicon.ico 可通过 https://yourdomain.com/favicon.ico 访问。
我是否需要编辑layout.tsx才能在App Router中添加图标？+
否，如果您使用文件约定（favicon.ico in /app）。如果您更喜欢代码，请导出带有图标属性的元数据对象。两种方法都会在渲染的 HTML 中生成相同的 `<link>` 标签。
Next.js 是否支持 SVG 图标？+
是的。对于 App Router，将 icon.svg 放在 /app 中；对于 Pages Router，在 _document.tsx 中添加 `<link rel='icon' type='image/svg+xml' href='/favicon.svg'>`。 App Router 自动从文件约定中发出 SVG 链接标记。
如何在 Next.js 中添加 apple-touch-icon？+
对于 App Router：将 apple-icon.png (180×180) 放入 /app 中。 Next.js 自动发出 apple-touch-icon 链接标签。对于 Pages Router：将 apple-touch-icon.png 放在 /public 中，并在 _document.tsx 中添加链接标签。
Next.js 会自动清除图标缓存吗？+
对于 /app 中的文件，是的 - Next.js 将内容哈希添加到所提供的文件名中，因此每个文件更改都会触发一次新的提取。对于 /public 中的文件，不会自动清除缓存；如果需要，手动附加查询字符串。
我可以在 Next.js 中的每个页面使用不同的图标吗？+
是的。在 App Router 中，使用自定义图标值导出特定路由的 page.tsx 中的generateMetadata 函数。在 Pages Router 中，在每页 `<Head>` 组件内添加一个“<link rel='icon'>”——它会覆盖文档级默认值。