你搭建好了一个简洁的 Streamlit dashboard，并把链接分享给团队，随后却有人问：“为什么浏览器标签页显示的是通用的 Streamlit logo，而不是我们自己的品牌标志？”解决办法就是一个你多半漏掉的参数：page_icon。本文会逐步演示如何使用本地图片、emoji 或 URL 设置 Streamlit favicon，并确认图标确实出现在浏览器标签页中。
page_icon 到底控制什么
Streamlit 会把 app 渲染到由它自行生成的页面中。st.set_page_config() 函数支持 page_icon 参数，用来指定浏览器标签页使用什么图标；在部分浏览器中，它还会影响书签图标。它并不提供完整的 HTML favicon 机制，而是 Streamlit 用来设置标签页图标的专用 hook。
按照 HTML 规范，favicon 需要通过文档 head 中的 rel="icon" link 声明（WHATWG HTML spec）。传入 page_icon 后，Streamlit 会替你处理这个 link。如果想进一步了解 favicon 是什么，以及它会出现在哪些位置，可以阅读我们的favicon 指南。
前置条件
- 一个可以正常运行的 Streamlit app（任何支持
st.set_page_config的版本均可）。 - 一个图标文件：正方形 PNG、JPG 或 SVG。为获得最佳效果，请使用至少 64×64 px 的正方形图片。
- 具备运行
streamlit run app.py的基础知识。
逐步设置 Streamlit favicon
第 1 步——先调用 set_page_config
st.set_page_config() 必须是脚本中执行的第一个 Streamlit 命令。如果在它之前调用 st.title() 或其他 Streamlit 函数，Streamlit 会抛出错误。请将它放在 app 文件的最顶部，也就是 import 语句之后。
import streamlit as st
st.set_page_config(
page_title="My Dashboard",
page_icon="icon.png"
)
st.title("My Dashboard")
第 2 步——让 page_icon 指向你的图片
page_icon 可以使用以下几种值：
- 项目中图片文件的相对路径，例如
"icon.png"。 - 绝对路径，例如
"/home/user/app/icon.png"。 - 图片的 URL，例如
"https://example.com/icon.png"。 - 单个 emoji 字符，例如
"🚀"。
如果要使用品牌图标，本地 PNG 或 SVG 是最稳妥的选择。将文件放在应用脚本所在目录，或者使用相对于执行 streamlit run 命令的位置的路径。
第 3 步——如果还没有图片，先用 emoji
做原型时，emoji 是最快的选择。Streamlit 会把它转换成标签页图标：
st.set_page_config(page_title="Prototype", page_icon="📊")
这对内部工具很方便，但和你的品牌风格并不相符。准备发布时，换成实际的图片文件即可。
第 4 步——准备合适的图标文件
Streamlit 支持常见图片格式，不过透明背景的正方形 PNG 在各种浏览器中效果最好。如果手头只有一个 logo，先裁剪出图形标志，再调整为 64×64 或 128×128 px。我们这篇从图片制作 favicon 的指南介绍了裁剪和简化步骤。
如果还需要在其他场景使用 ICO 文件，可以用 Mzu favicondl 将 PNG 转换过去。Streamlit 本身并不要求 ICO，不过，如果还要通过使用传统 favicon 的自定义域名提供应用，拥有一个 ICO 文件会很有帮助。
第 5 步——确认标签页图标
运行应用，在浏览器中打开它，然后查看标签页。如果看到的仍是默认 Streamlit 图标，请执行强制刷新（Ctrl+Shift+R 或 Cmd+Shift+R）。浏览器对 favicon 的缓存非常顽固，因此即使代码已经改过，旧图标也可能继续显示。如果需要更完整的排查清单，请参阅favicon 不显示。
常见陷阱
- 调用
set_page_config的时机太晚。 它必须是第一个 Streamlit 调用。把它移到顶部即可解决这个错误。 - 文件路径错误。 相对路径是相对于启动 Streamlit 的目录解析的，而不是脚本所在的文件夹。如果不确定，请使用绝对路径。
- 图片不是正方形。 过宽的 logo 会被压扁或出现留边（letterbox）。请先裁剪成正方形。
- 浏览器缓存。 标签页可能会在短时间内继续显示旧图标。执行强制刷新，或在隐私窗口中测试。
- 部署环境中的路径差异。 在 Streamlit Community Cloud 或 container 中，working directory 可能与本地环境不同。请使用相对于 app 文件的路径，或使用在部署环境中确实存在的绝对路径。
当你需要的不只是 page_icon
page_icon 只负责 Streamlit 应用自身在浏览器标签页中的图标。如果要把应用嵌入更大的网站，或者需要 Apple Touch icons 和 web app manifest，那就是另外的问题，需要由外围 HTML 处理。想了解完整的图标栈，请参阅我们的 favicon 最佳实践。
一旦知道该把文件放在哪里，设置 Streamlit favicon 只需改动一行。在脚本顶部调用 st.set_page_config(page_title=..., page_icon=...)，使用正方形 PNG 或 SVG，并通过强制刷新进行验证。这样就足以把标签页中的默认 Streamlit logo 替换成你自己的品牌图标。