本文旨在解决streamlit应用中html模板无法加载本地图片的问题。核心解决方案在于正确配置streamlit服务器以启用静态文件服务，并通过创建特定的`static`文件夹来组织本地图片资源。文章将详细阐述配置步骤、代码示例以及注意事项，确保开发者能够顺利在streamlit应用中集成并显示本地图片。
在开发Streamlit应用时，我们经常需要结合HTML模板来定制页面布局和样式。然而，一个常见的问题是，当尝试在HTML模板中引用本地图片（例如，使用
）时，这些图片往往无法正常显示，而外部链接的图片却可以。这并非Streamlit的限制，而是由于其默认的安全和效率设计，Streamlit应用默认不会直接暴露文件系统中的任意路径。要解决这个问题，我们需要明确地配置Streamlit以启用静态文件服务，并遵循特定的文件组织约定。
核心原因分析
Streamlit默认情况下不会自动服务应用程序目录中的任意文件。当你尝试在HTML模板中使用相对路径或绝对路径（如/img/ghog1.jpg）引用本地图片时，浏览器会向Streamlit服务器请求这些资源。但由于Streamlit服务器未配置为处理这些请求，它将无法找到并返回相应的图片文件，导致图片显示失败。对于外部链接图片，浏览器直接从外部服务器加载，不经过Streamlit，因此不受此限制。
解决方案
解决Streamlit应用中本地图片引用问题的关键在于两步：配置Streamlit服务器启用静态文件服务，以及将静态资源放置在Streamlit能够识别的特定目录中。
步骤一：配置Streamlit服务器启用静态文件服务
Streamlit允许通过配置文件.streamlit/config.toml来启用静态文件服务。你需要在这个文件中添加一个配置项。
立即学习“前端免费学习笔记（深入）”；
创建或编辑配置文件： 在你的Streamlit应用项目的根目录下（与app.py同级），创建一个名为.streamlit的文件夹（如果尚未存在）。 在该文件夹内，创建一个名为config.toml的文件（如果尚未存在）。
-
添加配置项： 在config.toml文件中，添加以下内容：
# .streamlit/config.toml [server] enableStaticServing = true
enableStaticServing = true这一行告诉Streamlit服务器，它应该监听并服务来自特定目录的静态文件请求。
步骤二：组织静态资源
配置启用静态文件服务后，你需要将所有本地图片、CSS、JavaScript等静态文件放置在一个Streamlit能够识别的特定文件夹中。Streamlit默认会查找一个名为static的文件夹。
创建static文件夹： 在你的Streamlit应用项目的根目录下（与app.py同级），创建一个名为static的文件夹。
-
放置图片文件： 将你需要引用的本地图片文件（例如ghog1.jpg）放入新创建的static文件夹中。 此时，你的项目结构可能如下所示：
my_streamlit_app/ ├── .streamlit/ │ └── config.toml ├── static/ │ └── ghog1.jpg └── app.py
步骤三：在HTML模板中正确引用图片
现在，你可以在HTML模板中引用static文件夹中的图片了。Streamlit会将static文件夹视为静态资源的根目录，因此在src属性中，你需要使用相对于static目录的路径，并以/static/作为前缀。
将原始的src="/img/ghog1.jpg"修改为src="/static/ghog1.jpg"。
示例代码
假设你的app.py中使用了st.markdown来渲染HTML模板：
-
.streamlit/config.toml 文件内容：
# .streamlit/config.toml [server] enableStaticServing = true
-
app.py 文件内容：
import streamlit as st # 假设 ghog1.jpg 位于项目的 static/ 目录下 # user_template 中引用本地图片 user_template = ''' ''' # bot_template 中引用外部图片（不受本地静态服务配置影响） bot_template = ''' ''' st.set_page_config(layout="wide") st.title("Streamlit 本地图片示例") st.markdown("### 用户消息模板 (包含本地图片)") st.markdown(user_template.replace("{{MSG}}", "这是来自用户的消息！"), unsafe_allow_html=True) st.markdown("### 机器人消息模板 (包含外部图片)") st.markdown(bot_template.replace("{{MSG}}", "这是来自机器人的消息！"), unsafe_allow_html=True) st.markdown("---") st.markdown("你也可以直接在 Streamlit 中使用本地图片：") st.image("static/ghog1.jpg", caption="使用 st.image 显示的本地图片", width=100) # 另一种在 markdown 中直接引用本地静态图片的方式 st.markdown("通过 Markdown 语法引用本地图片：") st.markdown("", unsafe_allow_html=True)
注意事项
- 路径约定：一旦enableStaticServing被设置为true，Streamlit会将static文件夹的内容映射到/static/路径下。这意味着，如果你的图片在static/images/profile.png，那么在HTML中引用时应使用src="/static/images/profile.png"。
- 配置文件位置：.streamlit/config.toml文件通常放置在应用的根目录。如果放置在用户主目录（~/.streamlit/config.toml），则会影响所有Streamlit应用。为了确保项目独立性，建议放在应用根目录。
- 部署环境：在部署Streamlit应用时，务必确保.streamlit/config.toml文件和static文件夹及其内容都被正确包含在部署包中，并保持正确的相对路径结构。
- 安全性：启用静态文件服务意味着static文件夹中的所有文件都将通过HTTP/HTTPS公开访问。请确保不要在static文件夹中放置任何敏感信息。
- 缓存：浏览器可能会缓存静态资源。如果你更新了图片但浏览器仍显示旧图片，可以尝试清除浏览器缓存或在开发过程中为图片URL添加版本号（例如/static/ghog1.jpg?v=2）。
总结
在Streamlit应用中通过HTML模板引用本地图片是一个常见的需求。通过遵循本文提供的步骤，即在.streamlit/config.toml中启用enableStaticServing配置，并将所有静态资源统一放置在项目根目录下的static文件夹中，并使用/static/前缀在HTML模板中引用，开发者可以轻松实现本地图片的加载和显示。这种方法不仅解决了图片不显示的问题，也使得静态资源的管理更加规范和高效。
