你的 FastAPI 应用已经运行起来,API 文档也很漂亮,但浏览器标签页里仍是一个空白方框,或者默认的地球图标。这个问题很常见:FastAPI 不会自动提供 favicon,也不像 Flask 或 Django 那样内置相关约定。只要清楚该把文件放在哪里,以及如何对外提供它,解决起来并不复杂。

本文会一步步介绍如何通过 StaticFiles、独立路由或 template tag 来提供 fastapi favicon。我们还会说明哪些 HTML 标记能让浏览器稳定识别图标,并梳理那些容易引发 404 或图标未刷新的问题。

前提条件

开始之前,请确认你具备以下条件:

步骤 1:将 favicon 文件放入静态目录

在项目根目录下创建一个名为 static 的文件夹(放在其他位置也可以),再把 favicon 文件放进去。为了尽可能兼容不同浏览器,将其命名为 favicon.ico;如果还有 PNG 或 SVG 版本,也一并保留。

myproject/
├── main.py
├── static/
│   └── favicon.ico
└── templates/
    └── index.html

如果手头只有 PNG 也能使用,只需在 HTML 中正确引用。浏览器在没有 link 标签时仍会请求 ICO 格式,因此让 /favicon.ico 可访问,可以避免控制台出现 404。

步骤 2:在 FastAPI 应用中挂载 StaticFiles

FastAPI 使用 Starlette 的 StaticFiles 提供静态资源。在 main.py 中加入以下代码:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount('/static', StaticFiles(directory='static'), name='static')

这样,static/ 下的任何文件都可以通过 /static/filename 访问。因此,你的 favicon 路径是 /static/favicon.ico。

步骤 3:在 HTML 中添加 link 标签

如果你的应用会提供 HTML 模板(使用 Jinja2Templates),请在基础模板的 <head> 中添加 favicon link。按照 HTML 规范,rel 属性必须设为 icon。

<link rel='icon' type='image/x-icon' href='/static/favicon.ico'>

如果还准备了 SVG 或 PNG 版本,请为它们分别设置合适的 type 属性。浏览器会自动选择受支持的最佳格式。想进一步了解 link 标签的排列顺序,可以阅读我们的 favicon link 标签指南。

第 4 步:直接提供 /favicon.ico(可选,但推荐)

即使页面中已有 link 标签,浏览器和某些工具仍会请求根路径下的 /favicon.ico。为避免出现 404,可以添加一个专门返回该文件的路由:

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/favicon.ico', include_in_schema=False)
async def favicon():
    return FileResponse('static/favicon.ico')

include_in_schema=False 可以避免该路由出现在自动生成的文档中。对于不提供 HTML、但仍希望 Network 面板保持整洁的纯 API 应用,这个路由尤其有用。

第 5 步:验证配置

启动服务器,然后在浏览器中打开应用。查看 Network 面板,favicon 请求应返回 200。如果看到 404,请确认文件路径正确,并且挂载点与 link 标签中的 URL 一致。你也可以使用 favicon 检查工具,审查图标在不同浏览器中的表现。

常见陷阱

结论

在 FastAPI 中提供 favicon,只需放置文件、挂载静态目录并添加正确的 link tag。对于仅提供 API 的应用,为 /favicon.ico 设置一个简单路由即可保持日志整洁。配置完成后,你的应用会在浏览器标签页、书签和历史记录中显示正确的图标——不再出现空白方块。