如果 Gradio 应用加载正常,但浏览器标签页仍显示通用的地球图标,说明应用缺少图标元数据。给 Gradio 添加 favicon 最简单的方式是通过启动器(launcher)配置,让 Gradio 注册图标文件,而不必手动修改它生成的页面模板。

无需在 gr.HTML 组件中放入 <link> 标签,也没必要为每个组件重复设置图标。只要在应用启动时配置一次,再确认浏览器确实请求了该文件即可。

准备工作

开始前,需要有一个可以重启的 Gradio 应用、一份正方形图标文件,以及对启动该应用的进程的访问权限。

如果设计稿最初采用 PNG 或 SVG 格式,请在部署前完成转换。可以使用 Mzu favicondl 创建 ICO 文件,并将生成的文件命名为 favicon.ico。PNG 转 ICO 指南介绍了可选尺寸。

1. 准备 favicon 文件

在 Python 入口点旁创建 assets 目录。将图标存放在路径稳定的位置,确保项目的每个副本——无论是本地、容器还是托管版本——都使用同一路径引用。

your-gradio-app/
├── app.py
└── assets/
    └── favicon.ico

图标应按浏览器标签页中的显示效果来设计,而不是按完整 logo 页面来设计。轮廓鲜明的图形或单个字母,通常比细小文字更能适应 16 像素的渲染。源图应保持正方形,也不要指望宽图总能以可预测的方式被裁剪。

2. 使用 launch() 设置 Gradio favicon

将文件的绝对路径传给 demo.launch() 的 favicon_path 参数。这是 Gradio 专用的配置项,不要把它写进 gr.Blocks()。

from pathlib import Path

import gradio as gr

app_dir = Path(__file__).resolve().parent
favicon = app_dir / 'assets' / 'favicon.ico'

if not favicon.is_file():
    raise FileNotFoundError(f'Favicon not found: {favicon}')

with gr.Blocks() as demo:
    gr.Markdown('# My Gradio app')

demo.launch(favicon_path=str(favicon))

Path(__file__).resolve().parent 这一表达式会以脚本所在位置为基准定位图标,而不是使用 shell 当前的执行目录。is_file() 检查会在启动流程继续运行前发现资源缺失或文件名拼写错误。该选项必须指向本地文件;远程图片 URL 不能代替可部署的资源文件。

3. 在本地验证图标

修改代码后,先停止正在运行的服务器,再重新启动。浏览器标签页很容易继续使用旧图标缓存,因此应在新标签页或隐私窗口中验证结果,不能只看原来的标签页。

查看页面源代码中的 <head> 部分,找到 rel 值为 icon 的 link 元素。HTML 规范将 icon 定义为一种用于外部资源的 link relation,浏览器可以单独获取对应文件,而不必将它与应用页面本身混在一起。

在开发者工具中打开 Network 面板并重新加载页面。确认图标请求返回 200 而不是 404,并核对响应内容确实是上传的文件。如果 link 元素已经存在,但标签页仍显示旧图标,可以使用更完整的favicon 排查清单,检查缓存以及相互冲突的图标链接。

4. 将资源文件与应用一起部署

部署时必须把图标和应用一起交付,而不只是放在自己的笔记本电脑上。最终交付包需要同时包含 app.py 和 assets/favicon.ico,并保持上文所示的相对位置。

当平台提供自己的站点图标设置时,同样的检查也很有必要。如果 Gradio app 被嵌入另一个页面,浏览器标签页的图标可能由顶层文档决定。在这种情况下,除了更新 Gradio launcher 的图标,也要更新父页面的图标。

常见误区

大多数 Gradio favicon 配置失败,都是几个小错误造成的:

结论

把 Gradio favicon 作为启动时管理的资源,是最简单稳妥的做法:将一个正方形的 ICO 文件放在 app 旁边,把解析后的路径传给 launch(favicon_path=...),并验证浏览器渲染图标时发出的请求。这样实现足够轻量,而且无论是本地还是托管的 Gradio app,标识更新时都只需替换同一个明确文件。