Hugo Favicon：自定义 Hugo 站点图标

你的 Hugo 站点可以正常构建，但浏览器标签页仍显示通用的页面图标。这通常意味着图标文件不在 Hugo 的发布资源路径中，或者生成的 HTML 根本没有引用它。稳妥的 Hugo favicon 配置需要将资源与模板分开处理：static/ 负责发布文件，layout partial 则负责添加浏览器所需的 <link> 元素。

前置条件

你需要准备一个现有的 Hugo 站点、一张正方形的 logo 或图标，并且能够访问站点的 layouts。如果主文件是 PNG 或 SVG，可以使用 Mzu favicondl 准备一个 ICO 备用文件，同时保留可用分辨率最高的原始设计稿。

一个现有的 Hugo 项目
正方形的 SVG 和 ICO 图标
项目和主题 layouts 的访问权限

四步添加 Hugo favicon

创建待发布的文件。 将原始设计稿转换为 favicon.svg 和 favicon.ico，然后把两者放入 Hugo 根目录下的 static/ 目录：
```
static/
  favicon.svg
  favicon.ico
```
static/ 中的文件会被原样复制，因此 Hugo 会将它们发布到站点根目录。
创建可复用的 partial。 新增 layouts/partials/head/favicon.html，写入：
```
<link rel='icon' href='{{ "favicon.ico" | relURL }}' sizes='any'>
<link rel='icon' href='{{ "favicon.svg" | relURL }}' type='image/svg+xml'>
```
HTML 规范定义了 icon link relation。这里使用 relURL，让生成的路径遵循 Hugo 的 base path，而不是假定站点位于域名根目录。
在 <head> 中渲染 partial。 在项目和当前使用的主题中查找包含文档 head 的 layout，并在其 head 结束标签前紧接着加入这一行：
```
<head>
  ...
  {{ partial "head/favicon.html" . }}
</head>
```
如果该文件属于主题，请先将文件复制到项目中对应的 layouts/ 路径；否则主题更新可能会覆盖这项修改。如果主题已经调用了 favicon partial，应直接修改该 partial，而不是再添加一个。
构建、预览并检查。 运行：
```
hugo
hugo server
```
打开本地站点，并通过浏览器开发者工具检查页面 head。确认生成的图标 URL 返回 200，同时检查生产构建完成后 public/favicon.svg 和 public/favicon.ico 是否存在。若要比较更多框架的实现方式，可参阅static site generator favicon guide。

常见误区

只把图标放在 assets/ 中。该目录用于存放由 Hugo 管理的资源。无需修改、直接对外提供的文件应放在 static/ 中，或者通过 Hugo 的 resource pipeline 处理。
把 /favicon.svg 写死。如果站点部署在子路径下，这种写法会导致失效。应使用 relURL 生成 URL。
只修改 theme 中的文件。升级 theme 时，该文件可能被覆盖。应尽可能把覆盖文件保留在项目自身目录中。
以为刷新后会立即更新。浏览器可能会缓存图标 URL。如果线上页面仍显示旧图标，请按照favicon 排查清单逐项检查。

确认最终效果

当生成的 head 中包含这两个 link 元素、所有被引用的文件都能成功返回，并且浏览器标签页显示预期图标时，就说明 Hugo favicon 已配置完成。将源图与生成文件分开保存，这样后续更新时结果更容易预测。

前置条件

四步添加 Hugo favicon

常见误区

确认最终效果

为 Hugo 站点准备 favicon