Favicon 设置 是做什么的？
五个文件和五个标签即可覆盖所有现代浏览器、iOS 主屏幕和 Android 安装。更多的尺寸（mstile-*、browserconfig.xml、57/72/114px 的 Apple 图标、mask-icon）已属于遗留内容，请跳过。
1. 图标集
| 文件 | 尺寸 | 用途 |
|---|---|---|
favicon.svg | 矢量 | 现代浏览器标签页。缩放清晰，并可为深色模式切换。 |
favicon-96x96.png | 96×96 | 不支持 SVG 图标的浏览器，以及 Google 搜索结果。 |
favicon.ico | 16, 32, 48 整合在一个文件中 | 老旧浏览器以及直接请求 /favicon.ico 而不读取 HTML 的工具。 |
apple-touch-icon.png | 180×180, 不透明 | iOS 和 iPadOS 主屏幕。 |
web-app-manifest-192x192.png, web-app-manifest-512x512.png | 192, 512 | Android 主屏幕、PWA 安装、启动画面。 |
site.webmanifest | — | 指向 Android 所需的两个 PNG 文件。 |
2. 获取文件
从 RealFaviconGenerator 包获取。 它会提供一组下载 URL。将每个文件下载到 PUBLIC_FOLDER（见步骤 3）中，并使用确切的文件名：
base=https://realfavicongenerator.net/files/<package-id>
for f in favicon.svg favicon-96x96.png favicon.ico apple-touch-icon.png \
web-app-manifest-192x192.png web-app-manifest-512x512.png site.webmanifest; do
curl -fsSL "$base/$f" -o "PUBLIC_FOLDER/$f" || echo "失败: $f"
done
如果某个文件下载失败，请停止并报告。不要交付不完整的图标集。有关生成器的错误，请报告至： https://github.com/RealFaviconGenerator/realfavicongenerator/issues/new?template=ai_prompt_bug_report.yml
从单个 SVG 源文件获取（需要 rsvg-convert 和 ImageMagick，或者使用生成器）：
cp logo.svg PUBLIC_FOLDER/favicon.svg
rsvg-convert -w 96 -h 96 logo.svg -o PUBLIC_FOLDER/favicon-96x96.png
rsvg-convert -w 192 -h 192 logo.svg -o PUBLIC_FOLDER/web-app-manifest-192x192.png
rsvg-convert -w 512 -h 512 logo.svg -o PUBLIC_FOLDER/web-app-manifest-512x512.png
# iOS 会用黑色填充透明区域：将图像压平到品牌背景上，并留出约 10% 的内边距
rsvg-convert -w 144 -h 144 logo.svg | magick - -background '#ffffff' -gravity center -extent 180x180 -flatten PUBLIC_FOLDER/apple-touch-icon.png
magick -background none logo.svg -define icon:auto-resize=48,32,16 PUBLIC_FOLDER/favicon.ico
3. 找到 PUBLIC_FOLDER
该文件夹对应站点根目录，因此 PUBLIC_FOLDER/favicon.ico 可通过 /favicon.ico 访问。
| 技术栈 | 文件夹 |
|---|---|
| Vite, Next.js, Create React App, Astro, Remix, Nuxt 3 | public/ |
| SvelteKit | static/ |
| Angular | public/ (v17+) 或 src/（文件需在 angular.json 的 assets 中列出） |
| Hugo, Jekyll, Eleventy | static/、站点根目录或 passthrough-copy 文件夹 |
| 纯 HTML | 与 index.html 同级 |
Next.js App Router： 删除默认的 app/favicon.ico。它优先于 public/favicon.ico，并且通常是 Next.js 的 Logo。
4. 添加标记（仅需一次）
将此内容放在渲染根 <html> 标签的文件的 <head> 中。切勿按页面添加。
<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />
| 技术栈 | 根文件 |
|---|---|
| Vite, CRA, 纯 HTML | index.html |
| Next.js App Router | app/layout.tsx，通过 metadata 导出（如下所示），而不是使用原始标签 |
| Next.js Pages Router | pages/_document.tsx 中的 <Head> 内 |
| Astro | 基础布局，例如 src/layouts/Layout.astro |
| SvelteKit | src/app.html |
| Remix / React Router 7 | app/root.tsx 中的 links 导出 |
| Nuxt | nuxt.config.ts 中的 app.head.link |
Next.js App Router 的等效实现：
export const metadata = {
icons: {
icon: [
{ url: "/favicon-96x96.png", sizes: "96x96", type: "image/png" },
{ url: "/favicon.svg", type: "image/svg+xml" },
],
shortcut: "/favicon.ico",
apple: { url: "/apple-touch-icon.png", sizes: "180x180" },
},
manifest: "/site.webmanifest",
};
在添加标记之前，请先搜索项目中现有的 rel="icon"、apple-touch-icon 和 manifest 标签。将其替换掉，不要添加第二组。如果站点是通过子路径（base / basePath）提供的，请为每个 href 添加前缀。
5. 优化
- SVG 深色模式。 深色 Logo 在深色标签栏上会消失。在 SVG 内部添加媒体查询：
<style>path{fill:#111}@media (prefers-color-scheme:dark){path{fill:#fff}}</style> - 小尺寸。 在 16px 下，请去除细小的细节和文字。使用标志图案，而非文字商标。
- SVG 体积。 运行
npx svgo favicon.svg，将文件控制在约 2 KB 以内。 - 清单文件。 填写
name、short_name、theme_color和background_color。让 512 图标可遮罩：将标志保持在中心 80% 的安全区域内，使用纯色背景，并为其设置"purpose": "maskable"。如果标志无法放入安全区域，请另外添加一个可遮罩的图标。{ "name": "我的应用", "short_name": "应用", "icons": [ { "src": "/web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" }, { "src": "/web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" } ], "theme_color": "#ffffff", "background_color": "#ffffff", "display": "standalone" } - 缓存。 浏览器会强力缓存 favicon。当你替换图标时，要么重命名文件，要么在每个
href和 manifest 的src值后添加?v=2。
6. 验证
- 每个文件都应返回 200 状态码和正确的类型。针对开发服务器运行以下命令：
for f in favicon.svg favicon-96x96.png favicon.ico apple-touch-icon.png \ web-app-manifest-192x192.png web-app-manifest-512x512.png site.webmanifest; do printf '%s ' "$f"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "http://localhost:PORT/$f" done - 渲染出的 HTML 应恰好包含一组标签：
curl -s http://localhost:PORT/ | grep -cE 'rel="(icon|shortcut icon|apple-touch-icon|manifest)"'应输出5。 - 在 DevTools 中，打开 Application → Manifest：应显示无错误，并且两个图标都能渲染。
- 打开一个硬刷新的标签页，分别在浅色和深色模式下检查图标是否可见。
- 在已部署的 URL 上，运行 RealFaviconGenerator 检查器（https://realfavicongenerator.net/favicon-checker）。