Jekyll favicon：适配 baseurl 的完整设置指南

favicon 即使能随 Jekyll 站点成功构建，站点使用 baseurl 时仍可能出问题：资源会生成到嵌套路径中，但 HTML 仍指向域名根目录。应将源文件放在静态目录中，通过 Jekyll 生成 URL，并在发布前检查构建产物。

前置条件

• 一个可编辑 layout 或 include 的 Jekyll 项目。
• 一个正方形 SVG、一个 ICO 后备图标，以及可选的 180×180 PNG。Mzu favicondl 可以从一张图片生成这些文件。
• 能够在本地运行 bundle exec jekyll build。

五步添加 Jekyll favicon

1. 创建固定的源文件目录

   将 favicon.svg、favicon.ico 和 apple-touch-icon.png 放入 assets/images/。不要直接修改 _site/；下次构建时，Jekyll 会重新创建该目录。

2. 在文档 head 中添加链接

   打开主题的 _includes/head.html，把这些标签插入到 head 元素结束标签之前。如果主题中没有这个 include 文件，就直接放到 _layouts/default.html 中。同时确认 layout 中仍然调用了 {% include head.html %}。

   <link rel='icon' type='image/svg+xml' href='{{ '/assets/images/favicon.svg' | relative_url }}'>
   <link rel='icon' sizes='16x16 32x32 48x48' href='{{ '/assets/images/favicon.ico' | relative_url }}'>
   <link rel='apple-touch-icon' sizes='180x180' href='{{ '/assets/images/apple-touch-icon.png' | relative_url }}'>

   HTML 规范将 rel='icon' 定义为指向图标资源的关联类型。把这些链接保留在 head 中，浏览器解析页面时就能发现它们。

3. 生成兼容 baseurl 的 URL

   在 _config.yml 中设置 baseurl，使其与实际部署路径一致。然后让所有图标路径都经过 Jekyll 的 relative_url filter 处理。该 filter 会添加配置中的 base path，因此同一套模板既能用于域名根目录，也能用于项目的子路径。不要把 href='/assets/images/favicon.svg' 写死，因为这样会忽略子路径。

4. 构建并检查生成的站点

   执行构建并启动本地服务器：

   bundle exec jekyll build
   bundle exec jekyll serve

   打开 _site/index.html，确认每个链接都包含预期的 base path。检查这三个文件是否都存在于 _site/assets/images/ 下。预览时，请使用 Jekyll 输出的兼容 baseurl 的 URL，不要想当然地认为站点从 / 开始。

5. 验证线上响应

   发布后，检查页面源代码，并直接请求 icon URL。页面必须引用部署后的实际路径，icon 请求也不能返回 404。如果旧图标仍然显示，可以重命名文件，或添加 favicon.svg?v=2 这样的查询参数。favicon 排障指南介绍了与缓存有关的检查方法。

常见误区

• 修改生成文件：对 _site/ 的改动会在下次构建时消失。
• 忽略 baseurl：以根路径开头的 URL 可能导致图标从错误的位置被请求。
• 保留重复链接：主题图标和自定义图标可能相互冲突。请从渲染后的 head 中移除不需要的链接。
• 把标记放在 body 中：应将链接移入 head include 或 layout 中。

结语

将资源放在 assets/ 下，在可复用的 head 模板中配置链接，并使用 relative_url 生成 URL，这样 Jekyll favicon 就能顺利从源码迁移到生产环境。有关格式选择和更多标签示例，请阅读 HTML favicon 指南。