Docusaurus Favicon 设置指南

如果替换资源后，Docusaurus 的 favicon 仍显示框架自带图标，通常是文件放错了目录，或配置没有指向它。把图标放进 static/，设置一项配置，再检查构建产物即可。

准备工作

你需要准备一个 Docusaurus 项目、一张正方形源图片，并确保能够修改 docusaurus.config.ts。

图片格式为 PNG 或 SVG，缩小到 16×16 像素后，标志仍然清晰可辨。
项目依赖已安装，并在仓库根目录打开终端。

用五个步骤添加 Docusaurus favicon

生成合适的文件。 使用 Mzu favicondl 将正方形 PNG 或 SVG 转换为 ICO，再下载 SVG 或 PNG。源图应尽量简洁；完整的字标放在浏览器标签页中会难以辨认。
使用 static/ 目录。 Docusaurus 会把该目录复制到构建产物中，不改变目录内部的路径。替换默认图标，或按下面的结构整理文件：
```
static/
└── img/
    ├── favicon.ico
    ├── favicon.svg
    └── favicon-32.png
```
设置内置配置项。 在 docusaurus.config.ts 的现有对象中保留或添加：
```
const config: Config = {
  // ...other options
  favicon: 'img/favicon.ico',
};
```
使用相对于 static/ 的路径，不要加前导斜杠。内置选项会添加图标链接并应用 baseUrl，因此无论站点部署在域名根目录还是子路径下，这项配置都能生效。
需要可缩放图标时，再添加 SVG。 在同一个配置对象中添加以下属性，同时保留 ICO 作为回退：
```
headTags: [
  {
    tagName: 'link',
    attributes: {
      rel: 'icon',
      type: 'image/svg+xml',
      href: '/img/favicon.svg',
    },
  },
],
```
该标签遵循 HTML 的 rel='icon' 链接关系。由于 headTags 按原样插入，需要包含基础路径：当 baseUrl: '/docs/' 时，应使用 /docs/img/favicon.svg。
构建并检查实际输出。 运行：
```
npm run build
npm run serve
```
检查渲染后的 <head>。其中应包含类似下面的图标链接：
```
<link rel='icon' href='/img/favicon.ico'>
```
确认 build/img/favicon.ico 确实存在，并查看 Network 面板中的响应：返回的应是图片，而不是 HTML。设置了 baseUrl 时，请检查带此前缀的 URL。部署完整的 build/ 目录。

常见误区

把文件放进 src/img：通过 import 引入的资源会随应用一起打包，不会自动发布到 /img/。这种配置应使用 static/ 目录。
忽略 baseUrl：baseUrl 配置项会正确处理路径，但 headTags 中直接写死的图标 URL 不会。
只检查缓存中的标签页：在无痕窗口中打开站点，或强制刷新。如果响应内容正确，但页面仍然显示旧内容，请使用favicon 排查清单。
添加重复的图标链接：检查生成的 head 中是否包含 theme 或 plugin 添加的标签。保留一个有意设置的 SVG 和一个 ICO fallback，删除意外重复的标签。
比较更通用的工作流：如需了解共通原则，可以参考static-site-generator favicon 指南；其中与 Docusaurus 相关的部分，是 favicon 配置项和 static/ 目录输出。

总结

设置 Docusaurus favicon 不需要页面级组件或 plugin。生成正确的文件，将其保存在 static/img/ 中，让 favicon 指向 ICO，并在每次部署或更改 base path 后检查构建生成的 head。

准备工作

用五个步骤添加 Docusaurus favicon

常见误区

总结

生成清晰的 Docusaurus 图标集