开发者实现 Logo 资源指南

快速实现概述

不同工具的文件目录不同。独立 Favicon Generator 的文件位于 ZIP 根目录，包含 favicon.ico、favicon-32x32.png、apple-touch-icon.png、site.webmanifest 和 integration-guide.html。服务端上传工作流则把图片放在 icons/、social/，代码放在 snippets/。

可以用favicon 案例包跟随本文操作，无需账户。先解压再复制文件，ZIP 下载地址不能直接作为图标地址。

以下示例把 favicon PNG、ICO 和 Apple Touch PNG 放在网站的 public/icons/，把独立工具生成的 manifest 放在 public/site.webmanifest。常见静态部署中，它们对应 /icons/... 与 /site.webmanifest。

如果把图标移动到 icons/，也要更新 manifest 中每个 src。Manifest 相对路径以 manifest 网址为基准，不是以 HTML 页面为基准。部署在子路径的网站，还应使用实际公开的基础路径。

基本 HTML 实现

先把实际导出文件映射到公开网址，再添加声明。

必要的 Meta 标签

<link rel="icon" href="/icons/favicon.ico">
<link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32x32.png">
<link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">

示例使用独立工具实际导出的文件名。只有对应工作流提供 SVG 时，才加入 SVG 声明；不要仅因旧清单出现 Safari 固定标签、Windows 或社交图片就添加相关声明，应先确认文件存在并适用于项目。

Web 应用清单配置

将独立 Favicon 包的 site.webmanifest 放在公开根目录，并把每个 src 改成真实部署路径。相对路径以 manifest 网址为基准，不以页面为基准。Manifest 不会自动实现离线缓存；标准与 maskable 图标示例见 PWA 指南。

框架特定实现

下面使用同一套导出文件，提供手动集成方法，不代表 LogoFoundry 额外生成了各框架安装包。除 SvelteKit 的资源占位符外，示例网址均以域名根目录部署为前提；子目录部署应匹配项目的基础路径。

Next.js 集成

选择一套图标配置并检查最终 head；文件约定可能覆盖 metadata 配置。

App Router（Next.js 13+）

可以在 app layout 使用以下 metadata，图片仍放在 public/icons/。另一种方式是使用 Next.js 的 app/favicon.ico、app/icon.png、app/apple-icon.png 文件约定。避免两套配置互相覆盖。详见 Next.js 图标文件约定与 metadata 配置。

import type { Metadata } from 'next';

export const metadata: Metadata = {
  icons: {
    icon: [
      { url: '/icons/favicon.ico' },
      { url: '/icons/favicon-32x32.png', type: 'image/png', sizes: '32x32' },
    ],
    apple: [{ url: '/icons/apple-touch-icon.png', sizes: '180x180' }],
  },
  manifest: '/site.webmanifest',
};

Manifest 描述图标和启动配置，不会自动实现离线缓存，也不能证明 PWA 可安装。原生 iOS 的 AppIcon.appiconset 与 Android res/ 应导入应用项目，不应放进 HTML head。

Pages Router（Next.js 12 及以下）

标题沿用原稿，Pages Router 并不限于 Next.js 12 及以下。已有 Pages Router 项目可将文件保存在 public/icons/，通过 next/head添加声明。共用声明可放在 pages/_app.tsx，并检查各页面是否另有冲突设置。

import Head from 'next/head';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Head>
        <link rel="icon" href="/icons/favicon.ico" key="favicon" />
        <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
        <link rel="manifest" href="/site.webmanifest" />
      </Head>
      <Component {...pageProps} />
    </>
  );
}

React（Vite/Create React App）

图片放在 public/icons/，manifest 放在 public/site.webmanifest。编辑的是项目根目录的 index.html，不是 React 组件或 public/index.html。使用 Vite HTML 入口的 Vue 项目也适用。参阅 Vite 公共资源说明。

<!-- 放入已有 index.html 的 head -->
<link rel="icon" href="/icons/favicon.ico">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">

Vite 复制 public 文件时保留文件名。配置了 base 的项目，应同时调整 HTML 与 manifest 的基础路径。构建后在实际部署目录测试首页和嵌套路由，不能只根据开发服务器判断路径正确。

维护已有 Create React App 项目时，应遵循该项目的 HTML 入口与公开基础路径约定，不要直接套用 Vite 根入口规则。

Astro

文件放在 public/，在共用布局（例如 src/layouts/Layout.astro）已有的 <head> 中添加声明，让使用此布局的页面都带上图标。文件复制规则参阅 Astro public 目录说明。

<!-- 放入共用 .astro 布局的 head -->
<link rel="icon" href="/icons/favicon.ico">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">

已经使用共用布局的页面，不需要重复声明。部署到子目录时，将实际基础路径加入公开网址，并检查 manifest 的图片引用。

高级实现技术

添加可选客户端行为之前，先让初始 HTML 提供正常图标。

动态网站图标更新

应用可以根据未读状态切换标签图标。初始 HTML 仍应提供常规图标，状态变化后只修改一个明确管理的 link。下面是可选示例，假设两张 PNG 都已另外制作并部署；它们不是标准 ZIP 额外交付的素材。

<link id="site-favicon" rel="icon" type="image/png" href="/icons/favicon-32x32.png">

function setUnreadIcon(unread) {
  const icon = document.querySelector('link#site-favicon');
  if (icon) {
    icon.setAttribute('href', unread
      ? '/icons/favicon-unread.png'
      : '/icons/favicon-32x32.png');
  }
}

路径应匹配实际部署基础路径。如果 head 由框架管理，应与框架的状态／head 机制整合，避免后续导航覆盖修改；不要反复追加图标 link。动态标签图标不会更新已安装 PWA 或 Google 搜索图标。主题配色可参阅深色 SVG 示例。

深色模式网站图标切换

自包含 SVG 可以使用 prefers-color-scheme。准备真实主题文件并测试浏览器选中的网址；参阅深色 SVG 示例。运行时标签图标切换不会更新已安装应用或搜索图标。

性能优化

先检查真实请求和最小图像，再增加提示或脚本。

预加载关键资源

不要默认预加载整套图标，也不要把 512px PNG 的 preload 写成安装加速保证。应先测量相关页面，再对确有需要的请求添加提示。

CDN 实现

CDN 地址应公开返回真实图片及恰当内容类型，head 使用实际网址。单独检查 CDN 缓存；多个图标声明不构成固定的回退顺序。

安全最佳实践

使用可信图稿，公开 SVG 前检查其内容。如果站点配置了 Content Security Policy 或独立资源域名，应检查控制台和对应图片、manifest 请求适用的策略，不要为了掩盖错误网址而放宽全站策略。公开图标和分享图应能在没有私有登录会话时直接返回图片。

内容安全策略

检查控制台和图片、manifest 请求适用的策略，只放行实际部署需要的位置。不要用复制来的局部 CSP 覆盖全站策略。

完整性检查

不要把示例校验值直接用于线上声明，也不要假定它证明 favicon 完整性。在构建／发布环节核对已知文件校验值与实际部署字节；浏览器完整性机制必须适用于具体资源类型。

测试和验证

分别核对文件、声明和实际显示。

自动化测试

DOM 中存在 link 只能证明声明存在。检查 getAttribute("href") 和 getAttribute("sizes")，再请求真实网址并验证内容类型、图片尺寸；返回 200 的 HTML 回退页仍不是图标。

常见问题排查

从公开网址和响应开始排查，再考虑图稿设计。

问题 1：网站图标不显示

1. 直接请求每张图标，核对 HTTP 状态、内容类型和尺寸。返回 200 但内容是 HTML 回退页，仍然不是有效图片。
2. 查看渲染后的 HTML head，排查重复或主题自动生成的声明。
3. 打开已部署 manifest，核对所有 src 能否返回对应 PNG。
4. 用 Favicon Checker检查公开文件，再到目标浏览器或安装后的应用中查看。
5. 仍显示旧图标时，对比声明网址与当前文件，清理相关浏览器、CDN、service worker 缓存，并用新的浏览器配置测试。修改查询参数只是诊断方法，不保证立即更新。

Google 搜索展示是独立过程，请按 Google favicon 指南配置；标签正确不代表即时显示。可复现的导出或文档问题请通过关于与联系反馈。

问题 2：显示错误尺寸

比较真实文件尺寸与 sizes 声明，排查框架重复配置，并区分小标签图与 manifest 启动器图。

问题 3：ICO 文件无法加载

确认真实 ICO 内容，不是改名 PNG 或 HTML 回退页。检查路由及内容类型，不要添加重复 Content-Type，也不要给频繁替换的无版本网址套用长期 immutable 缓存。

Logo Foundry 集成工作流程

按实际工具和输出目录完成集成。

1. 生成资源

独立 Favicon Generator与上传工作流输出布局不同，先查看文件清单再复制。

2. 实现代码片段

<link rel="icon" href="/icons/favicon.ico">
<link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32x32.png">
<link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">

示例使用独立工具实际导出的文件名。只有对应工作流提供 SVG 时，才加入 SVG 声明；不要仅因旧清单出现 Safari 固定标签、Windows 或社交图片就添加相关声明，应先确认文件存在并适用于项目。

3. 更新配置

可以在 app layout 使用以下 metadata，图片仍放在 public/icons/。另一种方式是使用 Next.js 的 app/favicon.ico、app/icon.png、app/apple-icon.png 文件约定。避免两套配置互相覆盖。详见 Next.js 图标文件约定与 metadata 配置。

import type { Metadata } from 'next';

export const metadata: Metadata = {
  icons: {
    icon: [
      { url: '/icons/favicon.ico' },
      { url: '/icons/favicon-32x32.png', type: 'image/png', sizes: '32x32' },
    ],
    apple: [{ url: '/icons/apple-touch-icon.png', sizes: '180x180' }],
  },
  manifest: '/site.webmanifest',
};

Manifest 描述图标和启动配置，不会自动实现离线缓存，也不能证明 PWA 可安装。原生 iOS 的 AppIcon.appiconset 与 Android res/ 应导入应用项目，不应放进 HTML head。

保留可编辑源图，公开部署目标场景需要的格式和尺寸。压缩副本后对比 16px、32px 实际图像：如果内部镂空消失，文件变小也不是有效优化。PNG 压缩没有一个可通用于所有图片的 JPEG 式质量百分比。

服务器应返回恰当的图片内容类型。CDN、service worker 和浏览器各有缓存，需要分别检查。采用带版本文件名时，在同一次发布中更新 HTML 与 manifest，并让旧文件在旧文档缓存期间继续可用。版本查询参数可辅助识别响应，却不能强制所有浏览器或已安装应用立即更新图标。

不要默认预加载整套图标；先检查实际网络请求和页面性能。反复通过脚本更换 favicon 也不能修复错误的部署路径。

部署清单

在生产构建的首页及嵌套路由检查实际文件。

部署前验证

发布前，在生产构建中打开首页和一个嵌套网址，确认未登录可访问图片及 manifest，所有引用对应真实文件，head 中是预期声明。分别测试相关浏览器的标签、书签和主屏幕安装。保留源图与已部署文件包，便于后续比较或回滚图标变化。

部署后测试

未登录请求图片与 manifest，检查最终 head，分别测试标签、书签和主屏幕安装。上传报告是图像统计提示与基础文件检查，不是 WCAG 测量或平台认证。

结论

按框架的真实公开目录约定配置，把声明与文件对应，再检查部署结果；这些步骤不保证所有浏览器完全相同。可复现的导出或说明问题可通过关于与联系反馈。