Streamlit 应用中静态文件（如图片）的配置与使用指南-Python教程-PHP中文网

Streamlit 应用中静态文件（如图片）的配置与使用指南

聖光之護

发布： 2025-10-14 12:26:23

原创

232人浏览过

Streamlit 应用中静态文件（如图片）的配置与使用指南

本教程旨在解决streamlit应用中html模板无法正确显示本地图片的问题。通过配置streamlit的`enablestaticserving`选项并规范静态文件的存放路径，开发者可以轻松地在streamlit应用中集成和展示本地图片资源，提升用户界面的丰富性和交互性。

在开发Streamlit应用时，我们经常需要将本地图片、CSS或JavaScript文件等静态资源集成到用户界面中，尤其是在使用st.markdown结合HTML模板进行定制化布局时。然而，初学者可能会遇到一个常见问题：尽管在HTML模板中引用了本地图片路径，但图片却无法正常显示，而外部链接图片则工作正常。这通常是因为Streamlit默认情况下不会将项目目录下的所有文件都作为可访问的静态资源进行服务。本教程将详细介绍如何正确配置Streamlit，以实现本地静态文件的有效管理和引用。

理解Streamlit的静态文件服务机制

许多Web框架，包括Streamlit，在默认情况下出于安全和效率考虑，并不会自动将项目目录下的任意文件暴露为可直接通过URL访问的静态资源。当你尝试在HTML模板中直接使用src="/img/your_image.jpg"这样的相对路径引用本地图片时，浏览器会向Streamlit服务器请求/img/your_image.jpg。如果Streamlit服务器没有明确配置来处理这类请求，它将无法找到对应的资源，导致图片加载失败。

Streamlit提供了一个专门的机制来解决这个问题：通过启用静态文件服务功能，并指定一个统一的目录来存放所有需要公开访问的静态资源。

配置enableStaticServing选项

要让Streamlit能够服务本地静态文件，我们需要在Streamlit的配置文件中启用一个特定的选项。

定位配置文件： Streamlit的全局配置文件通常位于用户根目录下的.streamlit/config.toml。
- 在Windows系统上，路径可能类似于 C:\Users\YourUser\.streamlit\config.toml。
- 在Linux或macOS系统上，路径通常是 ~/.streamlit/config.toml。如果该文件或.streamlit目录不存在，你可以手动创建它们。
添加或修改配置项： 打开或创建config.toml文件，并添加或修改以下配置：
```
# .streamlit/config.toml
[server]
enableStaticServing = true
```
登录后复制
enableStaticServing = true 这一行指令Streamlit服务器启用静态文件服务功能。保存并关闭文件。

组织静态文件目录

一旦启用了静态文件服务，Streamlit会约定在你的应用根目录下查找一个名为static的文件夹。所有你需要通过URL访问的本地图片、CSS文件、JavaScript文件等都应该存放在这个static文件夹内。

例如，如果你的Streamlit应用脚本是app.py，那么你的项目目录结构应该类似于：

your_streamlit_app/
├── .streamlit/
│   └── config.toml  # Streamlit配置文件
├── app.py           # Streamlit应用主脚本
└── static/          # 存放所有静态资源的目录
    ├── images/
    │   └── ghog1.jpg
    │   └── profile_pic.jpg
    └── styles/
        └── main.css

登录后复制

在应用中引用静态文件

配置完成后，你就可以在Streamlit应用中引用static文件夹内的静态文件了。无论是在HTML模板中还是通过Streamlit的Markdown语法，引用路径都应遵循特定的格式。

在HTML模板中引用： 在HTML模板（例如，通过st.markdown(html_content, unsafe_allow_html=True)加载的HTML字符串）中引用static文件夹内的文件时，路径应以/app/static/为前缀。
```

<div class="chat-message user">
    <div class="avatar">
        
        <img src="/app/static/images/ghog1.jpg" 
             style="max-height: 78px; max-width: 78px; border-radius: 50%; object-fit: cover;">
    </div>    
    <div class="message">{{MSG}}</div>
</div>
```
登录后复制
请注意，这里的/app/static/是Streamlit内部约定好的URL前缀，它映射到你的项目根目录下的static文件夹。

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

56

查看详情

通过Streamlit的st.markdown中引用： 同样，在Streamlit的Markdown语法中引用图片，也遵循相同的路径规则。

import streamlit as st

st.title("Streamlit 静态图片展示示例")

# 假设 myimage.png 位于 your_streamlit_app/static/ 目录下
st.markdown("[![点击我](app/static/myimage.png)](https://streamlit.io)")

# 或者在更复杂的HTML结构中嵌入
html_content = """
<div style="text-align: center; margin-top: 20px;">
    <img src="/app/static/images/profile_pic.jpg" alt="本地图片" 
         style="width: 200px; height: auto; border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);">
    <p style="font-style: italic; color: #555;">这是一张来自本地静态目录的图片。</p>
</div>
"""
st.markdown(html_content, unsafe_allow_html=True)

登录后复制

完整示例

为了更好地演示上述步骤，以下是一个完整的Streamlit应用示例：

1. 文件结构：

my_streamlit_app/
├── .streamlit/
│   └── config.toml
├── app.py
└── static/
    └── profile_pic.jpg  # 确保你在此处放置一张图片，例如一张用户头像

登录后复制

2. .streamlit/config.toml 内容：

[server]
enableStaticServing = true

登录后复制

3. app.py 内容：

import streamlit as st

st.set_page_config(layout="wide")
st.title("Streamlit 静态图片服务演示")

# 使用 HTML 模板引用本地图片
st.markdown("""
<div style="display: flex; align-items: center; gap: 20px; padding: 20px; border: 1px solid #ddd; border-radius: 10px; background-color: #f9f9f9;">
    <div class="avatar">
        <img src="/app/static/profile_pic.jpg" 
             alt="用户头像"
             style="max-height: 100px; max-width: 100px; border-radius: 50%; object-fit: cover; border: 3px solid #6c5ce7;">
    </div>
    <div>
        <h2>Streamlit 用户</h2>
        <p>这是一个通过Streamlit静态文件服务加载的本地头像示例。请确保图片路径正确。</p>
    </div>
</div>
""", unsafe_allow_html=True)

st.write("---")
st.subheader("通过 Markdown 语法引用图片")
st.markdown("你也可以直接在 `st.markdown` 中使用Markdown语法引用本地图片：")
st.markdown("![示例图片](/app/static/profile_pic.jpg '本地头像示例')")

st.write("---")
st.info("提示：请确保你的 `profile_pic.jpg` 文件位于 `my_streamlit_app/static/` 目录下，并且 `.streamlit/config.toml` 中已设置 `enableStaticServing = true`。")

登录后复制

运行此应用（streamlit run app.py），你将看到profile_pic.jpg图片被成功加载并显示在页面上。

注意事项与最佳实践

配置文件路径： 务必确保config.toml文件放置在正确的.streamlit目录下。Streamlit会优先加载用户根目录下的配置，然后是项目根目录下的配置。
路径前缀： 始终使用/app/static/作为引用static文件夹内静态资源的URL前缀。
安全性： 启用静态文件服务意味着static文件夹下的所有内容都将公开可访问。避免在此目录中存放任何敏感信息。
缓存： 浏览器可能会缓存静态资源。如果你更新了图片但页面上未显示最新版本，尝试清除浏览器缓存或使用Ctrl+F5（Windows/Linux）或Cmd+Shift+R（macOS）强制刷新页面。
部署： 在部署Streamlit应用到生产环境时（例如Streamlit Cloud），通常不需要额外配置静态文件服务，因为这些平台有自己的文件服务机制，并且通常会遵循类似的约定或提供专门的上传/管理静态资源的选项。但本地开发时的配置是理解其工作原理的基础。