Streamlit网页背景图不显示且无报错问题求助

可能的原因及修复方案 #

1. Streamlit DOM结构变更，选择器错误 #

Streamlit新版本中，页面主容器的CSS类为.stApp而非body，原代码里的body选择器无法正确定位页面容器，导致背景样式不生效。

修复：将CSS中的body替换为.stApp，同时可添加额外样式优化显示效果：

.stApp {
    background-image: url("data:image/png;base64,%s");
    background-size: cover;
    background-repeat: no-repeat;
    background-attachment: fixed;
}

2. 缓存装饰器过时 #

原代码使用的@st.cache(allow_output_mutation=True)在Streamlit 1.21.0+版本已被弃用，可能引发缓存异常，导致图片数据读取失败。

修复：替换为新版缓存装饰器@st.cache_data（适用于处理可序列化的二进制数据）：

@st.cache_data
def get_base64_of_bin_file(bin_file):
    with open(bin_file, 'rb') as f:
        data = f.read()
    return base64.b64encode(data).decode()

3. 图片路径问题 #

即便图片与.py文件同目录，运行环境的工作目录可能并非脚本所在目录（比如IDE默认工作目录为项目根目录），导致无法找到图片文件。

修复：通过__file__获取脚本绝对路径，拼接图片路径：

import os
current_dir = os.path.dirname(os.path.abspath(__file__))
png_path = os.path.join(current_dir, 'wallpaper.png')
set_png_as_page_bg(png_path)

4. 缺失必要模块导入 #

确保代码开头导入所需模块：

import streamlit as st
import base64
import os

完整修复后的代码 #

import streamlit as st
import base64
import os

@st.cache_data
def get_base64_of_bin_file(bin_file):
    with open(bin_file, 'rb') as f:
        data = f.read()
    return base64.b64encode(data).decode()

def set_png_as_page_bg(png_file):
    bin_str = get_base64_of_bin_file(png_file)
    page_bg_img = '''
    <style>
    .stApp {
        background-image: url("data:image/png;base64,%s");
        background-size: cover;
        background-repeat: no-repeat;
        background-attachment: fixed;
    }
    </style>
    ''' % bin_str
    
    st.markdown(page_bg_img, unsafe_allow_html=True)

current_dir = os.path.dirname(os.path.abspath(__file__))
png_path = os.path.join(current_dir, 'wallpaper.png')
set_png_as_page_bg(png_path)

额外排查步骤 #

• 检查图片文件是否损坏：用图片查看器打开wallpaper.png，确认文件可正常显示。
• 查看浏览器控制台：打开Streamlit页面的开发者工具（F12），切换到Console标签，排查是否存在隐藏的加载或CSS解析错误。

内容的提问来源于stack exchange，提问作者K80