如果你的 Flutter Web 应用在浏览器标签页中仍显示默认的 Flutter 标志,通常应在 web/index.html 中修复,而不是在 Dart widget 中处理。Flutter web favicon 是一张静态图片,浏览器会单独于应用 UI 请求它。

你需要从 Flutter 的 Web 外壳中链接这张图片,将 web app manifest 中的图片分开处理,然后重新构建静态输出。整个过程无需修改 Dart 代码。

前置条件

用六步添加 Flutter web favicon

  1. 检查 Flutter 的 Web 入口文件

    打开 web/index.html,搜索 rel='icon'。Flutter 模板中可能已经包含默认的图标链接,因此应替换原有引用,避免同时保留两套互相冲突的图标链接配置。

    也要打开 web/manifest.json。其中的 icons 数组用于提供已安装 Web 应用的图标图像,但不能替代接下来要添加的浏览器标签页图标链接。

  2. 准备静态图标文件

    使用 Mzu favicondl 制作一套正方形图标。导出 SVG、16 像素和 32 像素 PNG、多尺寸 ICO、180 像素 Apple touch image,以及供 manifest 使用的 192 像素和 512 像素 PNG。

    将文件放在 web/icons/ 下,这样 Flutter 会把它们与其他静态 Web 资源一并复制:

    web/
    ├── index.html
    ├── manifest.json
    └── icons/
        ├── favicon.svg
        ├── favicon-16.png
        ├── favicon-32.png
        ├── favicon.ico
        ├── apple-touch-icon.png
        ├── icon-192.png
        └── icon-512.png
  3. 将图标链接添加到 HTML head

    HTML 标准通过 rel='icon' 关联图标资源。在 web/index.html 的 <head> 元素中添加一套明确、完整的图标链接:

    <link rel='icon' type='image/svg+xml' href='icons/favicon.svg'>
    <link rel='icon' type='image/png' sizes='32x32' href='icons/favicon-32.png'>
    <link rel='icon' type='image/png' sizes='16x16' href='icons/favicon-16.png'>
    <link rel='icon' href='icons/favicon.ico'>
    <link rel='apple-touch-icon' href='icons/apple-touch-icon.png'>

    移除模板中的旧图标链接,并将 Apple touch 项单独保留,因为它对应不同的展示位置。

  4. 更新 Web App Manifest

    对于以 PWA 形式安装的 Flutter Web 应用,确认 web/index.html 中包含 <link rel='manifest' href='manifest.json'>。如果缺少该链接,就将其添加到 head 中,然后更新 web/manifest.json 中已有的 icons 数组。manifest 的其他键保持不变。

    [
      {
        "src": "icons/icon-192.png",
        "sizes": "192x192",
        "type": "image/png"
      },
      {
        "src": "icons/icon-512.png",
        "sizes": "512x512",
        "type": "image/png"
      }
    ]

    这些文件用于支持已安装应用的各种显示场景,不能替代 HTML 页面骨架中显式声明的 rel='icon' 链接。

  5. 构建并检查生产版本输出

    构建生产版本站点:

    flutter build web --release

    检查 build/web/index.html 和 build/web/icons/。构建后的 index 应包含新链接,且每个被引用的文件都应存在。

    如果应用从子目录提供服务,请使用 host 所期望的相同 base path 进行构建:

    flutter build web --release --base-href=/portal/

    这样,icons/favicon.svg 等相对路径就会以生成的 base URL 为基准进行解析。

  6. 在浏览器开发者工具中验证请求

    在本地启动服务器,托管生产版本输出:

    python3 -m http.server 8000 --directory build/web

    打开 http://localhost:8000。在浏览器开发者工具中,确认这些链接位于 document head 中。在 Network 面板中筛选 favicon,禁用缓存后重新加载,确认图标请求返回 200。

    还要在部署后的 HTTPS URL 上重复请求检查,因为即使本地目录完全正确,host 仍可能使用不同的 base path 或阻止该资源加载。

常见误区

结论

当源文件位于 web/、HTML 中包含一套干净的 icon stack、manifest 路径与同一批 assets 匹配,并且 production build 能够提供所有被引用的文件时,Flutter web favicon 才算配置完成。这样的结构既能让浏览器标签页图标与 Dart rendering 分离,也能为部署中的每个图标提供可预测的 URL。