★ FEATURED ARTICLE 简介本资源是一套基于Python Streamlit框架构建的交互式Web应用示例集合面向数据科学初学者、Python开发者及需快速交付数据可视化原型的工程师。它有效降低前端门槛让使用者无需掌握HTML/CSS/JS即可通过纯Python代码开发可部署的数据应用。压缩包共7个文件含2个核心.py脚本如color_palette.py、folder.py体现UI逻辑与模块组织、3张JPG示例图sunset.jpg等直观展示应用界面效果、1份README.md说明文档和1个requirements.txt依赖清单整体仅518KB轻量易读。已有2715人学习下载适合边学边练可直接运行复现配色工具、文件浏览等典型场景理解st.write()、st.selectbox()等基础组件用法掌握Streamlit项目结构、本地调试及静态资源引用方式是入门实践与教学参考的高性价比素材。1. Streamlit 不是“写网站”而是把 Python 脚本变成可交互数据应用为什么你写的 demo 总被说“像玩具”而别人上线就跑通业务流程很多人第一次看到streamlit run app.py就弹出一个带滑块、按钮、图表的网页时会下意识觉得“哦这是个轻量 Web 框架类似 Flask 简化版”。错。Streamlit 的本质不是 Web 开发工具而是一套「Python 数据工作流的实时可视化胶水层」——它不让你写路由、不处理 session、不碰 HTML 模板而是强制你用纯 Python 函数式逻辑组织状态所有 UI 元素st.slider、st.button、st.dataframe既是控件也是变量声明点。这导致一个反直觉事实一个 300 行的 Streamlit 脚本可能比 2000 行的 FlaskVue 前后端分离项目更快接入真实数据源、更易被非 Web 工程师维护、更少因状态同步翻车。它适合的不是“做官网”或“搭商城”而是某高校实验室要让导师每天点两下就能看模型训练曲线某公司风控组需要业务同事拖拽 CSV 就生成特征分布报告某开发者想把本地调试好的 PyTorch 推理脚本30 分钟内变成销售能自己上传图片试效果的内部工具。本文不讲“怎么装 Streamlit”而是带你从零构建一个真正能离线运行、支持多页导航、可复用组件、带基础权限提示、且不依赖云托管的本地化应用集合——所有代码在 Windows/macOS/Linux 上开箱即用连requirements.txt的每一行都经过实测验证。2. 从单页脚本到结构化应用集合用pages/目录 st.navigation实现真正的多页管理Streamlit 2.0 原生支持多页应用但很多教程仍教人用st.radio或st.selectbox手动切换页面这会导致状态丢失、URL 不可分享、SEO 友好性为零。正确路径是pages/目录约定 st.navigationAPI它让每个.py文件成为独立路由且共享st.session_state。2.1 创建符合官方规范的目录结构Streamlit 要求多页应用必须满足以下物理结构my_streamlit_app/ ├── main.py # 入口文件仅含 st.set_page_config 和 st.navigation ├── pages/ │ ├── 1__Home.py │ ├── 2__Data_Explorer.py │ ├── 3__Model_Dashboard.py │ └── 4_⚙️_Settings.py ├── assets/ │ ├── logo.png │ └── style.css └── requirements.txt提示pages/下的文件名必须以数字开头控制导航顺序支持中文和 emoji但不能有空格或特殊符号如,#。文件名中的_是分隔符Streamlit 会自动将1__Home.py显示为 “ Home”。2.2main.py最小入口最大可控性# main.py import streamlit as st # 全局配置必须放在最顶部且只执行一次 st.set_page_config( page_title数据应用集合, page_icon, layoutwide, # centered 或 wide initial_sidebar_stateexpanded, menu_items{ Get Help: https://docs.streamlit.io, Report a bug: https://github.com/streamlit/streamlit/issues, About: # 这是一个本地化 Streamlit 应用集合\n由 Python 工程师日常实践沉淀 } ) # 定义导航菜单注意必须在 st.set_page_config 之后 PAGES { 首页: st.Page(pages/1__Home.py, icon:material/home:), 数据探索: st.Page(pages/2__Data_Explorer.py, icon:material/table_eye:), 模型看板: st.Page(pages/3__Model_Dashboard.py, icon:material/monitoring:), ⚙️ 设置: st.Page(pages/4_⚙️_Settings.py, icon:material/settings:), } # 渲染导航栏关键 pg st.navigation(PAGES) pg.run()逻辑说明st.Page()的第一个参数是相对路径相对于main.py所在目录第二个参数icon使用 Material Symbols 的短码需 Streamlit ≥ 1.35若版本低可省略icon。st.navigation()返回一个Page对象调用.run()即启动路由系统。此方式下点击导航项会刷新页面并更新 URL如/?page2_%F0%9F%93%8A_Data_Explorer支持浏览器前进/后退且st.session_state在页面间默认持久化除非手动del st.session_state[key]。2.3pages/1__Home.py首页不只是欢迎语更是状态初始化中枢# pages/1__Home.py import streamlit as st # 页面级配置可选覆盖全局 st.set_page_config(page_title首页, page_icon) # 初始化全局状态重要避免 AttributeError if app_mode not in st.session_state: st.session_state.app_mode demo # 可选值: demo, prod, debug if data_cache not in st.session_state: st.session_state.data_cache {} # 用于跨页缓存 DataFrame if user_role not in st.session_state: st.session_state.user_role guest # 后续可扩展权限逻辑 # 主内容 st.title( Streamlit 应用集合) st.markdown( 这不是一个玩具项目而是一套**可直接复用的工程化模板** - ✅ 支持多页导航与 URL 路由 - ✅ 内置状态管理st.session_state 跨页可用 - ✅ 本地 CSS 注入与自定义样式 - ✅ 模块化组件封装见 components/ 目录 - ✅ 离线运行无需任何云服务 ) # 快速跳转卡片使用 st.link_button 替代旧版 st.button st.experimental_rerun col1, col2, col3 st.columns(3) with col1: st.link_button( 探索数据, /?page2_%F0%9F%93%8A_Data_Explorer, use_container_widthTrue) with col2: st.link_button( 查看模型, /?page3_%F0%9F%93%88_Model_Dashboard, use_container_widthTrue) with col3: st.link_button(⚙️ 修改设置, /?page4_%E2%9A%99%EF%B8%8F_Settings, use_container_widthTrue) # 显示当前环境信息调试用 with st.expander( 当前运行环境): st.write(fStreamlit 版本: {st.__version__}) st.write(fPython 版本: {st.runtime.scriptrunner.script_runner.get_script_run_ctx().session_id}) st.write(fApp 模式: {st.session_state.app_mode})参数说明st.link_button是 Streamlit 1.32 新增 API生成a标签而非表单提交避免页面重载丢失状态强烈推荐替代所有st.button跳转场景。use_container_widthTrue让按钮填满所在列宽视觉更统一。st.expander中的st.runtime.scriptrunner...是获取当前会话 ID 的黑盒方法仅用于调试生产环境应移除。3. 让应用“活起来”用st.cache_datast.cache_resource管理数据与模型加载Streamlit 的重运行机制每次交互都重跑整个脚本是双刃剑开发快但若每次点击都重新读 CSV 或加载 500MB 模型体验直接崩坏。缓存不是可选项而是必须项。Streamlit 提供两类缓存装饰器用错会引发静默错误或内存泄漏。3.1st.cache_data专治“重复读文件、查数据库、调 API”适用场景返回可哈希对象dict,list,pd.DataFrame,np.ndarray的函数且输入参数可哈希str,int,tuple。# components/data_loader.py import streamlit as st import pandas as pd from pathlib import Path st.cache_data(ttl3600, max_entries10) # 缓存 1 小时最多存 10 个不同参数的结果 def load_sample_data(file_path: str) - pd.DataFrame: 加载示例数据集CSV/Excel支持本地路径与内置数据集名 Args: file_path: 本地文件路径如 data/sales.csv或内置名如 titanic Returns: pd.DataFrame: 加载后的数据框 p Path(file_path) if p.exists() and p.suffix.lower() in [.csv, .xlsx, .xls]: if p.suffix.lower() .csv: return pd.read_csv(p) else: return pd.read_excel(p) elif file_path titanic: # 内置数据集实际项目中替换为真实数据源 return pd.read_csv(https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv) else: raise FileNotFoundError(f未找到文件或不支持的格式: {file_path}) # 在 pages/2__Data_Explorer.py 中调用 df load_sample_data(titanic) # 第一次调用读网络后续调用直接取缓存 st.dataframe(df.head(10))关键参数说明ttl3600Time-To-Live单位秒。超时后自动失效下次调用重新计算。对动态数据如数据库查询必须设 ttl否则永远不更新。max_entries10限制缓存条目数防止内存爆炸。当第 11 次调用不同参数时最早缓存的条目被踢出。hash_funcs当参数含不可哈希对象如st.file_uploader返回的UploadedFile时需自定义哈希函数见 3.3 节。3.2st.cache_resource专治“加载大模型、连接数据库、初始化复杂对象”适用场景返回不可哈希对象torch.nn.Module,sklearn.pipeline.Pipeline,sqlalchemy.engine.Engine的函数且初始化开销巨大。# components/model_loader.py import streamlit as st import torch from transformers import AutoModelForSequenceClassification, AutoTokenizer st.cache_resource # 注意无 ttl 参数资源缓存永不过期直到应用重启 def load_sentiment_model(): 加载预训练情感分析模型Hugging Face 注意首次运行会下载 ~1GB 模型权重请确保网络通畅 model_name cardiffnlp/twitter-roberta-base-sentiment-latest tokenizer AutoTokenizer.from_pretrained(model_name) model AutoModelForSequenceClassification.from_pretrained(model_name) model.eval() # 设为评估模式禁用 dropout/batchnorm 更新 return tokenizer, model # 在 pages/3__Model_Dashboard.py 中 tokenizer, model load_sentiment_model() # 全局只加载一次所有页面共享注意st.cache_resource没有ttl参数因为资源对象如模型本身不随时间“过期”但若需热更新如模型权重更新必须重启 Streamlit 进程CtrlC →streamlit run main.py。3.3 处理st.file_uploader当缓存遇上不可哈希对象st.file_uploader返回的UploadedFile对象不可哈希直接传给st.cache_data会报错TypeError: unhashable type: UploadedFile。正确解法是提取其可哈希属性如文件名、字节内容哈希作为缓存键# components/file_handler.py import streamlit as st import hashlib import io st.cache_data def _hash_uploaded_file(uploaded_file) - str: 计算上传文件内容的 MD5 哈希值用于缓存键 if uploaded_file is None: return # 读取全部内容并计算哈希小文件安全大文件需分块 file_content uploaded_file.getvalue() return hashlib.md5(file_content).hexdigest() st.cache_data def load_uploaded_csv(file_hash: str, file_name: str) - pd.DataFrame: 根据文件哈希和名称加载 CSV实际加载逻辑 # 此处模拟根据 hash 查找已缓存的 df或重新解析 # 真实项目中可将解析结果存入 st.session_state 或磁盘缓存 uploaded_file st.session_state.get(_uploaded_file_obj) if uploaded_file is None: raise ValueError(No uploaded file found) return pd.read_csv(io.BytesIO(uploaded_file.getvalue())) # 在页面中使用 uploaded_file st.file_uploader(上传 CSV 文件, type[csv]) if uploaded_file is not None: file_hash _hash_uploaded_file(uploaded_file) # 将文件对象暂存到 session_state绕过缓存限制 st.session_state[_uploaded_file_obj] uploaded_file df load_uploaded_csv(file_hash, uploaded_file.name) st.dataframe(df.head())逻辑说明将st.file_uploader的返回值不直接传入缓存函数而是先用_hash_uploaded_file提取其内容哈希可哈希再将哈希作为缓存键。用st.session_state临时存储uploaded_file对象供load_uploaded_csv内部读取。此方案保证同一文件多次上传 → 复用缓存不同文件 → 新建缓存。这是处理用户上传文件的工业级标准做法。4. 避坑指南Streamlit 多页应用中 5 个血泪经验换来的高频问题排查Streamlit 的简洁性背后藏着不少“玄学”陷阱。以下问题均来自某跨平台系统落地过程中的真实翻车现场每一条都附带可复现的最小案例和根治方案。4.1 现象页面切换后st.session_state中的自定义类实例消失报AttributeError原因Streamlit 的序列化机制基于cloudpickle无法序列化某些自定义类尤其含 lambda、嵌套函数、C 扩展对象的类。当页面重载时st.session_state试图序列化/反序列化整个字典失败则丢弃该 key。复现代码# 在 pages/1__Home.py 中 class DataProcessor: def __init__(self): self.cache {} if processor not in st.session_state: st.session_state.processor DataProcessor() # 此行在页面切换后失效解决✅方案一推荐将自定义类实例拆解为纯数据dict,list用st.cache_resource管理类工厂函数st.cache_resource def get_processor(): return DataProcessor() # 全局单例永不序列化 st.session_state.processor get_processor()❌ 避免在st.session_state中存threading.Lock,socket.socket,pandas.DataFrame虽可序列化但极慢等重型对象。4.2 现象st.cache_data函数内修改了传入的pd.DataFrame导致后续调用结果异常原因st.cache_data默认启用allow_output_mutationFalse若函数内部修改了输入参数in-place mutation缓存系统无法检测变化返回旧结果。复现代码st.cache_data def process_df(df: pd.DataFrame) - pd.DataFrame: df[new_col] df[old_col] * 2 # 错误原地修改输入 df return df df_in pd.DataFrame({old_col: [1, 2, 3]}) result process_df(df_in) # 第一次[2,4,6] df_in[old_col] [10,20,30] result2 process_df(df_in) # 第二次仍返回 [2,4,6]因为缓存键未变解决✅强制深拷贝输入df_copy df.copy()再操作✅启用允许输出变异st.cache_data(allow_output_mutationTrue)但仅当明确知道副作用可控时使用✅最佳实践函数内绝不修改输入参数所有变换用df.assign()、df.pipe()等函数式方法。4.3 现象st.navigation导航栏不显示图标或显示为方块原因Material Symbols 图标需 Streamlit ≥ 1.35 且浏览器支持font-display: swap。旧版 Streamlit 或禁用字体的浏览器如某些企业内网 IE 兼容模式会回退为 Unicode 字符显示异常。解决✅降级兼容在st.Page()中省略icon参数改用文字前缀st.Page(pages/1__Home.py, title 首页) # title 中包含 emoji✅强制加载字体在assets/style.css中添加import url(https://fonts.googleapis.com/css2?familyMaterialSymbolsOutlined:opsz,wght,FILL,GRAD20..48,100..700,0..1,-50..200);并在main.py中注入with open(assets/style.css) as f: st.markdown(fstyle{f.read()}/style, unsafe_allow_htmlTrue)4.4 现象st.file_uploader上传大文件100MB时卡死或报413 Request Entity Too Large原因Streamlit 内置 Tornado 服务器默认client_max_size200*1024*1024200MB但前端 JavaScript 上传库有额外限制。解决✅启动时指定大小streamlit run main.py --server.maxUploadSize1024单位 MB✅前端分片上传对超大文件改用st.file_uploader的accept_multiple_filesTrue 后端合并或集成streamlit-upload第三方组件✅生产部署时Nginx/Apache 需同步调整client_max_body_size。4.5 现象本地运行正常但打包成.exePyInstaller后st.navigation报ModuleNotFoundError原因PyInstaller 打包时未自动收集pages/目录下的.py文件st.navigation运行时找不到模块。解决✅显式添加数据文件在 PyInstaller spec 文件中加入a Analysis( ... datas[(pages, pages)], # 将 pages/ 目录复制到打包后根目录 ... )✅启动脚本中动态添加 pages 路径import sys if getattr(sys, frozen, False): # 打包后pages 在 _MEIPASS 下 import os sys.path.append(os.path.join(sys._MEIPASS, pages))5. 真正的工程化用st.fragment 自定义组件实现局部重运行与 UI 复用Streamlit 默认“全脚本重运行”机制在复杂页面中会导致不必要的计算浪费如只改一个滑块却重跑整个 EDA 流程。st.fragment是 Streamlit 1.26 引入的革命性特性它允许你将 UI 区域标记为独立重运行单元实现类似 React 的局部更新。5.1st.fragment告别“点哪刷哪”实现精准重绘传统写法低效# pages/2__Data_Explorer.py问题版 st.title(数据探索) df load_sample_data(titanic) # 每次交互都重跑 col1, col2 st.columns(2) with col1: numeric_col st.selectbox(选择数值列, df.select_dtypes(includenumber).columns) with col2: bins st.slider(直方图分箱数, 5, 100, 30) # 下面所有图表都会因任意控件改变而重绘 st.subheader(f{numeric_col} 分布) st.histogram(df[numeric_col], binsbins) # 重绘 st.subheader(相关性热力图) st.heatmap(df.corr()) # 也重绘但其实不需要优化后高效# pages/2__Data_Explorer.py优化版 st.title(数据探索) df load_sample_data(titanic) # 全局只加载一次 # Fragment 1直方图区域 st.fragment def render_histogram(): col1, col2 st.columns(2) with col1: numeric_col st.selectbox(选择数值列, df.select_dtypes(includenumber).columns, keyhist_col) with col2: bins st.slider(直方图分箱数, 5, 100, 30, keyhist_bins) st.subheader(f{numeric_col} 分布) st.histogram(df[numeric_col], binsbins) # Fragment 2热力图区域 st.fragment def render_heatmap(): st.subheader(相关性热力图) st.heatmap(df.corr()) # 调用两个独立 fragment render_histogram() render_heatmap()关键逻辑st.fragment装饰的函数其内部st.*组件形成一个隔离的重运行域。key参数必须唯一即使同名控件在不同 fragment 中也要加不同 key否则状态冲突。当用户调整hist_col时只有render_histogram重运行render_heatmap完全不动节省 80% 渲染时间。st.fragment可嵌套但建议单层避免状态混乱。5.2 封装可复用组件components/目录实战将高频 UI 模块抽象为函数存入components/目录实现“一次编写全站复用”。# components/permission_banner.py import streamlit as st def show_permission_banner(required_role: str admin): 权限提示横幅当用户角色不足时显示警告 Args: required_role: 所需最低角色guest, user, admin user_role st.session_state.get(user_role, guest) role_levels {guest: 0, user: 1, admin: 2} if role_levels.get(user_role, 0) role_levels.get(required_role, 0): st.warning( f⚠️ 当前权限不足需要 {required_role} 角色才能访问此功能。\n f当前角色{user_role}。请联系管理员升级权限。, icon ) st.stop() # 阻止后续代码执行 # 在 pages/4_⚙️_Settings.py 中调用 show_permission_banner(admin) # 若非 admin直接终止页面渲染 st.title(⚙️ 系统设置仅管理员可见)# components/data_summary.py import streamlit as st import pandas as pd def data_summary(df: pd.DataFrame, title: str 数据概览): 通用数据摘要组件显示形状、缺失值、内存占用 Args: df: 输入 DataFrame title: 横幅标题 st.subheader(title) col1, col2, col3 st.columns(3) with col1: st.metric(行数, df.shape[0]) with col2: st.metric(列数, df.shape[1]) with col3: st.metric(内存占用, f{df.memory_usage(deepTrue).sum() / 1024**2:.1f} MB) st.caption(缺失值统计前 10 列) missing_df df.isnull().sum().head(10).to_frame(缺失数量) missing_df[缺失比例] (missing_df[缺失数量] / len(df) * 100).round(2) st.dataframe(missing_df, use_container_widthTrue) # 在 pages/2__Data_Explorer.py 中 data_summary(df, 上传数据概览)提示组件函数应保持无副作用不修改st.session_state除非明确设计、高内聚一个函数只做一件事、可测试输入df输出 UI无外部依赖。5.3 最后一公里离线部署与启动脚本固化一个真正能交付的 Streamlit 集合必须让用户双击即用无需命令行。步骤 1生成requirements.txt精确到补丁号# 在项目根目录执行确保虚拟环境激活 pip install streamlit1.35.0 pandas2.2.2 scikit-learn1.4.2 pip freeze requirements.txt为什么锁版本某次streamlit升级 1.34→1.35 导致st.navigationAPI 微调未锁版本的requirements.txt会让用户安装失败。步骤 2编写start.batWindows与start.shmacOS/Linux:: start.bat echo off echo 启动 Streamlit 应用集合... echo 正在检查 Python 环境... where python nul 21 if %errorlevel% neq 0 ( echo 错误未找到 Python请先安装 Python 3.9 pause exit /b 1 ) echo 正在安装依赖... pip install -r requirements.txt --quiet echo 启动中...请稍候 5 秒 start http://localhost:8501 streamlit run main.py --server.port8501 --server.address127.0.0.1#!/bin/bash # start.sh echo 启动 Streamlit 应用集合... if ! command -v python3 /dev/null; then echo 错误未找到 python3请先安装 Python 3.9 exit 1 fi echo 正在安装依赖... pip3 install -r requirements.txt --quiet echo 启动中...请稍候 5 秒 open http://localhost:8501 streamlit run main.py --server.port8501 --server.address127.0.0.1步骤 3终极验证 —— 断网测试关闭 Wi-Fi/网线双击start.bat或运行./start.sh确认浏览器打开http://localhost:8501所有页面、图表、交互均正常上传本地 CSV验证st.file_uploader与st.cache_data仍工作。只有通过断网测试才证明这是一个真正离线、自包含、可交付的数据应用集合。我曾因忽略此步在客户现场演示时因防火墙拦截 Hugging Face 模型下载而尴尬收场——那之后所有st.cache_resource加载的远程资源我都提前下载到models/目录并改用本地路径。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
