如果 Blazor 应用能够正常运行,但浏览器标签页里显示的还是默认文档图标,通常是因为缺少 static file,或文档 head 中没有对应的 link。要让 Blazor favicon 稳定生效,两者都需要:应用提供图标资源,文档 head 中包含 rel='icon' 链接。Blazor 常见的各种 hosting model 都适用这套做法。

前置条件

开始前需要准备一个现有的 Blazor 项目、.NET SDK,以及一张正方形 logo。如果源文件是 PNG,可以使用 Mzu favicondl 分别生成 SVG、ICO 和 PNG 文件。

1. 确认模板及其 head 文件

打开上面提到的文件,检查其中的 head。在 Blazor Web App 中,编辑 Components/App.razor;在 standalone WebAssembly 中,编辑 wwwroot/index.html。在 hosted WebAssembly 中,编辑客户端 index,但需要确认部署后的 server 会提供相关资源。如果旧版模板使用 Pages/_Host.cshtml,则改为编辑该文档。不要把全局图标放在普通页面组件中,因为这样可能只对某一条 route 生效。

2. 准备一组小尺寸图标

创建一个目录,用于存放各个 icon variant:

wwwroot/
└── favicon/
    ├── favicon.svg
    ├── favicon.ico
    └── apple-touch-icon.png

把这些文件放在 wwwroot 下,使其作为 static web assets 发布。我们推荐使用可缩放的 SVG,以及包含 16、32 和 48 px 图像的 ICO;也可以选用 180×180 PNG,作为 touch shortcut。图案应保持正方形并留出 padding,同时去掉细小的文字,因为文字在 16 px 下会消失。可以使用 Mzu favicondl 转换或打包这些文件。

3. 将 Blazor favicon 链接添加到文档 head

在包含 base URL 和 stylesheet 链接的同一个 head 中添加全局链接:

<head>
  <base href='/' /&gt;

  <link rel='icon' href='favicon/favicon.ico'
        sizes='16x16 32x32 48x48' /&gt;
  <link rel='icon' type='image/svg+xml'
        href='favicon/favicon.svg' /&gt;
  <link rel='apple-touch-icon' sizes='180x180'
        href='favicon/apple-touch-icon.png' /&gt;
</head>

这些相对 URL 会跟随应用的 base path,而不会假定图标位于域名根目录。HTML Standard 对 rel='icon' 的定义指出,它描述的是一种外部资源图标;type 和 sizes 用于描述文件。保留 ICO 链接作为 fallback,并统一定义一组全局图标配置,不要在每个 component 中重复添加。

4. 更新 WebAssembly 项目

对于 standalone WebAssembly,将同样的链接粘贴到 wwwroot/index.html 的 head 中。对于 hosted WebAssembly,把这些链接添加到客户端 index,发布 solution,然后检查服务器输出:

dotnet publish -c Release

确认发布后的 wwwroot 中包含 favicon 文件夹。如果没有,就将其复制到宿主的 wwwroot 中,或调整静态资源发布配置。即使客户端 index 工作正常,图标请求仍可能返回 404。

5. 检查静态文件服务

如果直接请求图标时返回 404,请检查 Program.cs 中是否有 app.UseStaticFiles(),或者是否已经配置了 static-assets endpoint mapping。如果两者都不存在,请在 routing 和 endpoint registration 之前插入:

app.UseStaticFiles();

不要替换整个 pipeline,也不要重复添加已有的 static-asset 处理。缺少这一步时,页面仍可能正常渲染,但 /favicon/favicon.ico 的请求会失败。standalone WebAssembly 不需要 ASP.NET Core middleware,因为它的发布结果是一个静态站点。

6. 验证文件和浏览器标签页

使用 dotnet run 运行项目,将下面的 5000 替换为控制台输出的端口,然后分别直接请求这两个文件:

curl -I http://localhost:5000/favicon/favicon.ico
curl -I http://localhost:5000/favicon/favicon.svg

每次响应都应返回 200,且 Content-Type 为图片类型。查看页面源代码,确认 link 元素位于 head 中。如果 HTML 正确,但标签页仍显示旧图标,请打开新标签页或无痕窗口,并检查 Network 面板。普通的强制刷新可能不会替换已经缓存的图标。

在部署后的 URL 上重复检查。localhost 验证成功,并不能证明生产环境使用了相同的 base path,或提供了相同的文件。

常见问题

总结

根据 hosting model 配置 head 文件,将资源放在 wwwroot 下,并用相对路径声明全局 URL。调试标签页之前,先直接测试这些文件。对于非标准服务器配置,可参阅更完整的 ASP.NET Core favicon 设置参考。