Streamlit应用中HTML模板引用本地图片资源的最佳实践-Python教程-PHP中文网

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

DDD

发布： 2025-10-13 13:37:13

原创

177人浏览过

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

本文旨在解决streamlit应用中html模板无法加载本地图片的问题。核心解决方案在于正确配置streamlit服务器以启用静态文件服务，并通过创建特定的`static`文件夹来组织本地图片资源。文章将详细阐述配置步骤、代码示例以及注意事项，确保开发者能够顺利在streamlit应用中集成并显示本地图片。

在开发Streamlit应用时，我们经常需要结合HTML模板来定制页面布局和样式。然而，一个常见的问题是，当尝试在HTML模板中引用本地图片（例如，使用<img src="/img/ghog1.jpg">）时，这些图片往往无法正常显示，而外部链接的图片却可以。这并非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/作为前缀。

AppMall应用商店

AI应用商店，提供即时交付、按需付费的人工智能应用服务

查看详情

将原始的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 = '''
<div class="chat-message user">
    <div class="avatar">
        <img src="/static/ghog1.jpg" style="max-height: 78px; max-width: 78px; border-radius: 50%; object-fit: cover;">
    </div>    
    <div class="message">{{MSG}}</div>
</div>
'''

# bot_template 中引用外部图片（不受本地静态服务配置影响）
bot_template = '''
<div class="chat-message bot">
    <div class="avatar">
        <img src="https://i.ibb.co/cN0nmSj/Screenshot-2023-05-28-at-02-37-21.png" 
style="max-height: 78px; max-width: 78px; border-radius: 50%; object-fit: cover;">
    </div>
    <div class="message">{{MSG}}</div>
</div>
'''

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模板中引用，开发者可以轻松实现本地图片的加载和显示。这种方法不仅解决了图片不显示的问题，也使得静态资源的管理更加规范和高效。

以上就是Streamlit应用中HTML模板引用本地图片资源的最佳实践的详细内容，更多请关注php中文网其它相关文章！