Streamlit应用中HTML模板引用本地图片资源的最佳实践

本文旨在解决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来启用静态文件服务。你需要在这个文件中添加一个配置项。

立即学习“前端免费学习笔记（深入）”；

1. 创建或编辑配置文件： 在你的Streamlit应用项目的根目录下（与app.py同级），创建一个名为.streamlit的文件夹（如果尚未存在）。 在该文件夹内，创建一个名为config.toml的文件（如果尚未存在）。

2. 添加配置项： 在config.toml文件中，添加以下内容：

   # .streamlit/config.toml
   [server]
   enableStaticServing = true

   enableStaticServing = true这一行告诉Streamlit服务器，它应该监听并服务来自特定目录的静态文件请求。

步骤二：组织静态资源

配置启用静态文件服务后，你需要将所有本地图片、CSS、JavaScript等静态文件放置在一个Streamlit能够识别的特定文件夹中。Streamlit默认会查找一个名为static的文件夹。

1. 创建static文件夹： 在你的Streamlit应用项目的根目录下（与app.py同级），创建一个名为static的文件夹。

2. 放置图片文件： 将你需要引用的本地图片文件（例如ghog1.jpg）放入新创建的static文件夹中。 此时，你的项目结构可能如下所示：

   my_streamlit_app/
   ├── .streamlit/
   │   └── config.toml
   ├── static/
   │   └── ghog1.jpg
   └── app.py

步骤三：在HTML模板中正确引用图片

现在，你可以在HTML模板中引用static文件夹中的图片了。Streamlit会将static文件夹视为静态资源的根目录，因此在src属性中，你需要使用相对于static目录的路径，并以/static/作为前缀。

Paraflow

AI产品设计智能体

下载

将原始的src="/img/ghog1.jpg"修改为src="/static/ghog1.jpg"。

示例代码

假设你的app.py中使用了st.markdown来渲染HTML模板：

1. .streamlit/config.toml 文件内容：

   # .streamlit/config.toml
   [server]
   enableStaticServing = true

2. app.py 文件内容：

   import streamlit as st
   
   # 假设 ghog1.jpg 位于项目的 static/ 目录下
   # user_template 中引用本地图片
   user_template = '''
   
       
   
           @@##@@
       
       
       
   {{MSG}}
   
   '''
   
   # bot_template 中引用外部图片（不受本地静态服务配置影响）
   bot_template = '''
   
       
   
           @@##@@
       
       
   {{MSG}}
   
   '''
   
   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("![本地图片示例](/static/ghog1.jpg)", 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模板中引用，开发者可以轻松实现本地图片的加载和显示。这种方法不仅解决了图片不显示的问题，也使得静态资源的管理更加规范和高效。