Streamlit 集合项目实战：从 Python 脚本到交互式 Web 应用

简介这份资源是面向Python开发者与数据可视化学习者的Streamlit实战项目合集适合希望快速上手数据驱动Web应用、又不想深陷前端技术栈的工程师、分析师与学生。压缩包共7个文件约518KB以2个py脚本、3张jpg示例图片、1个txt依赖说明和1个md文档为主涵盖应用入口、配色工具与演示素材结构轻量便于直接运行与二次修改。已有2719人学习下载说明其在入门与练手场景中具备一定参考价值。通过研究其中的示例代码读者可以掌握应用基本结构搭建、结合Pandas处理数据、集成可视化图表、添加按钮与下拉菜单等交互元素以及自定义布局与本地部署的完整思路从而把零散知识点串成可复用的开发流程提升数据应用构建效率。1. 用 Streamlit 把 Python 脚本变成能点的网站这个集合项目值得拆一遍如果你写过数据分析脚本大概率遇到过这种尴尬逻辑跑通了结果也打印在终端里但想给别人看的时候要么截图要么让对方装环境跑命令行。Streamlit 解决的就是这个最后一公里的问题——它让你用纯 Python 写交互页面不用碰 HTML、CSS、JavaScript一个streamlit run app.py就能在浏览器里打开一个能点、能拖、能输入的网站。这次要拆的这个项目就是一个把多个 Streamlit 小站攒在一起的集合仓库每个子目录是一个独立可运行的应用覆盖数据展示、表单交互、图表可视化这些典型场景。它适合两类人刚学完 Python 想找个能出成果的练手项目的以及手里有一堆脚本想快速包装成内部工具的。下面我按「这堆应用怎么组织、单个应用怎么跑、核心交互怎么写、想改的时候从哪下手」的顺序把它拆开讲。2. 项目结构拆解一个仓库装多个 Streamlit 应用怎么组织2.1 目录布局与入口约定这类集合型仓库最常见的组织方式是按应用分目录每个目录里放一个主入口文件根目录再放一份依赖清单和说明。我拿到手第一件事是看目录树因为它直接决定了你跑哪个命令、装哪些包。典型结构长这样streamlit-apps/ ├── app.py # 有时根目录也放一个聚合入口或首页 ├── requirements.txt # 全局依赖或每个子目录各一份 ├── README.md ├── data_visualizer/ # 应用一数据可视化 │ ├── app.py # 该应用的入口 │ ├── requirements.txt # 该应用独立依赖可选 │ └── data/ │ └── sample.csv ├── form_demo/ # 应用二表单交互 │ └── app.py ├── image_tool/ # 应用三图像处理小工具 │ └── app.py └── utils/ # 跨应用复用的工具函数 └── helpers.py判断入口有个简单规则Streamlit 应用的主文件通常叫app.py或main.py里面一定会有st.开头的调用。你cd进哪个子目录就对哪个app.py执行streamlit run。如果根目录也有app.py那多半是个导航首页用st.sidebar或st.tabs把子应用串起来。注意不要试图在根目录一条命令跑起所有子应用。Streamlit 一次只服务一个入口脚本集合仓库的「集合」体现在目录并列不是运行时聚合。2.2 依赖管理与环境隔离集合仓库最容易翻车的地方就是依赖冲突。应用 A 要pandas1.5应用 B 要pandas2.0装在一个环境里必炸。合格的做法是每个子应用一份requirements.txt用独立虚拟环境跑。我一般这么操作# 进入某个子应用目录 cd data_visualizer # 建独立虚拟环境避免和其他应用打架 python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate # 装该应用自己的依赖 pip install -r requirements.txt # 启动 streamlit run app.py如果仓库只有一份全局requirements.txt那说明作者假设所有应用依赖版本兼容这种情况先整体装一遍跑哪个报缺包再单独补。参数上streamlit run默认端口是 8501被占用时加--server.port 8502换端口想让同网段其他人访问加--server.address 0.0.0.0但仅限可信内网别往公网暴露。2.3 应用之间的复用边界集合仓库里通常有个utils/或common/目录放跨应用复用的东西比如数据加载函数、统一的样式设置、缓存装饰器。这里有个坑Streamlit 的脚本是以入口文件所在目录为工作目录运行的子应用import utils时Python 的模块搜索路径不一定包含仓库根目录。常见解法是在子应用入口顶部手动把根目录加进sys.pathimport sys import os # 把仓库根目录加入模块搜索路径保证能 import 到 utils ROOT os.path.dirname(os.path.dirname(os.path.abspath(__file__))) if ROOT not in sys.path: sys.path.append(ROOT) from utils.helpers import load_csv # 现在可以正常导入这段代码的作用是动态计算仓库根目录并注入sys.path。__file__是当前脚本路径两次dirname拿到根目录判断后再 append避免重复添加。参数上没什么可调的注意abspath别省否则相对路径在不同启动目录下会算错。如果你的应用是独立部署的这段可以删掉改成把utils直接复制进子目录。3. 跑起来从零启动一个子应用的完整步骤3.1 环境准备与最小验证在动任何应用代码之前先确认 Streamlit 本身能跑。这一步能帮你把「环境问题」和「应用问题」分开省得后面排查时两头猜。# 确认 Python 版本Streamlit 一般要求 3.8 以上 python --version # 装 Streamlit如果 requirements 里没锁版本先装最新稳定版 pip install streamlit # 跑官方自带的 hello 示例验证环境没问题 streamlit hellostreamlit hello会启动一个内置的演示应用并自动打开浏览器。如果这一步能看到页面说明 Streamlit 安装、端口、浏览器都没问题。如果卡住或报端口占用先解决这个再往下走。这一步是我每次拿到新机器的固定动作相当于给环境做个体检。3.2 启动子应用并读懂启动日志环境验证通过后进具体子应用目录启动cd form_demo streamlit run app.py启动后终端会打印两行关键信息一个是Local URL本机访问地址通常是http://localhost:8501一个是Network URL同网段访问地址。第一次跑如果页面空白先看终端有没有报错堆栈Streamlit 的报错会直接打在终端里比浏览器控制台清楚。页面右上角有个Rerun和Always rerun选项改代码后 Streamlit 默认会提示你是否重跑选Always rerun可以做到保存即刷新开发时很省事。提示Streamlit 的默认行为是「每次交互都从头执行整个脚本」所以脚本顶层的耗时操作读大文件、请求接口一定要用st.cache_data缓存否则每次点按钮都重新跑一遍体验会很卡。3.3 数据文件与路径问题集合里的应用经常带示例数据比如data/sample.csv。读取时用相对路径还是绝对路径直接决定应用换个目录跑会不会崩。稳妥写法是基于脚本位置拼路径import os import pandas as pd import streamlit as st # 基于当前脚本位置定位数据文件避免受启动目录影响 BASE_DIR os.path.dirname(os.path.abspath(__file__)) DATA_PATH os.path.join(BASE_DIR, data, sample.csv) st.cache_data # 缓存读取结果避免每次交互重复读盘 def load_data(path): return pd.read_csv(path) df load_data(DATA_PATH) st.dataframe(df)BASE_DIR保证无论你从哪个目录执行streamlit run数据路径都算得对。st.cache_data是 Streamlit 的数据缓存装饰器第一次调用读盘后续相同参数直接返回缓存。参数上cache_data适合返回 DataFrame、字典这类可序列化数据如果缓存的是数据库连接、模型对象这类不可序列化的东西要用st.cache_resource。这两个装饰器用混了是新手高频翻车点报错信息通常是「cannot hash argument」。4. 核心交互代码Streamlit 的输入、输出与状态管理4.1 常用输入控件与回调Streamlit 的交互模型很直白控件函数返回当前值脚本从上到下重新执行用返回值驱动后面的逻辑。下面这段覆盖了最常见的几类输入import streamlit as st st.title(交互控件演示) # 文本输入返回字符串 name st.text_input(你的名字, value) # 滑块返回数值min/max/step 控制范围 age st.slider(年龄, min_value0, max_value120, value25, step1) # 下拉选择返回选中的选项 city st.selectbox(城市, [北京, 上海, 广州, 深圳]) # 多选返回列表 hobbies st.multiselect(爱好, [读书, 运动, 音乐, 旅行]) # 按钮返回布尔值只在被点击的那次运行为 True if st.button(提交): st.write(f{name}{age} 岁来自 {city}爱好{, .join(hobbies)})每个控件函数的第一个参数是显示标签value是默认值key是控件唯一标识多控件同标签时必须指定否则 Streamlit 会报重复 ID。st.button的返回值只在被点击的那一次脚本执行里为True这是它和输入控件的关键区别——输入控件的值会一直保留按钮是瞬时事件。理解这一点才能正确安排「点击后做什么」的逻辑位置。4.2 会话状态跨交互保存数据因为脚本每次交互都重跑普通变量存不住东西。要在多次交互间保留数据得用st.session_stateimport streamlit as st # 初始化计数器只在第一次运行时设置 if count not in st.session_state: st.session_state.count 0 # 两个按钮分别增减 col1, col2 st.columns(2) with col1: if st.button(加一): st.session_state.count 1 with col2: if st.button(减一): st.session_state.count - 1 st.write(f当前计数{st.session_state.count})st.session_state是个类字典对象跨脚本重跑保持存活。初始化时用if key not in st.session_state判断避免每次重跑都重置。st.columns(2)把页面横向分成两列with col1:上下文管理器把控件放进对应列。这套组合是做计数器、购物车、多步表单的基础。踩过的坑是直接在按钮回调里改session_state而不判断初始化第一次运行会报KeyError所以初始化那步别省。4.3 图表与布局输出Streamlit 原生支持多种图表也能直接嵌 Matplotlib、Plotly 的图。布局上st.sidebar放筛选条件主区域放结果是最常见的模式import streamlit as st import pandas as pd import numpy as np # 侧边栏放筛选控件 st.sidebar.header(筛选条件) n_points st.sidebar.slider(数据点数量, 10, 500, 100) # 生成示例数据 df pd.DataFrame( np.random.randn(n_points, 2), columns[x, y] ) # 主区域分两个标签页展示 tab1, tab2 st.tabs([折线图, 原始数据]) with tab1: st.line_chart(df) with tab2: st.dataframe(df)st.sidebar后面的控件自动进侧边栏不用额外包裹。st.tabs做标签页切换适合把「图」和「表」分开放。st.line_chart是原生图表传 DataFrame 直接画零配置要更精细的控制就换st.pyplot或st.plotly_chart。参数上原生图表对中文列名支持一般列名建议用英文显示层再做映射。5. 避坑与排查跑 Streamlit 集合项目常踩的五个坑5.1 端口被占用启动直接失败现象是终端报Port 8501 is already in use应用起不来。原因是上一个 Streamlit 进程没退干净或者别的服务占了这个端口。解决方式是换端口启动streamlit run app.py --server.port 8502或者先找出占用进程杀掉。我习惯在开发时固定用 8501起冲突就往上加别去动系统服务占用的端口。5.2 改了代码页面不刷新现象是保存文件后浏览器没反应还是旧结果。原因是 Streamlit 默认不会自动重跑需要你在页面右上角手动确认或者开了Always rerun才会保存即刷新。解决方式是点右上角菜单选Always rerun或者在启动配置里设runOnSave true。注意开了自动重跑后如果脚本顶层有耗时操作又没缓存每次保存都会卡一下所以缓存要提前加好。5.3 缓存装饰器用错导致报错现象是启动时报UnhashableParamError或cannot hash argument。原因是把不可哈希的参数比如列表、字典、自定义对象直接传给了st.cache_data装饰的函数或者该用cache_resource的地方用了cache_data。解决方式是给参数加下划线前缀跳过哈希检查如_conn或者把数据库连接、模型这类资源改用st.cache_resource。判断标准很简单返回数据用cache_data返回连接或全局资源用cache_resource。5.4 中文显示成方块现象是图表里的中文标签变成一个个方框。原因是 Matplotlib 默认字体不含中文。解决方式是在绘图前指定中文字体import matplotlib.pyplot as plt # 指定支持中文的字体按系统实际有的字体名填 plt.rcParams[font.sans-serif] [SimHei] # Windows 常见 plt.rcParams[axes.unicode_minus] False # 解决负号显示为方块Linux 或 macOS 上字体名不同用fc-list :langzh查系统里有哪些中文字体填进去。axes.unicode_minus那行是配套的不设的话负号也会变方块。5.5 子应用导入 utils 失败现象是ModuleNotFoundError: No module named utils。原因是 Streamlit 以入口脚本所在目录为工作目录仓库根目录不在模块搜索路径里。解决方式是在子应用入口顶部把根目录注入sys.path代码见 2.3 节。另一个更省事的办法是把utils做成可安装的本地包pip install -e .但集合型小项目一般用前者就够了。6. 二次开发把集合里的应用改成自己的工具拿到这个集合最实际的用法不是原样跑而是挑一个最接近你需求的应用改成自己的。我一般按「换数据源 → 调交互 → 加缓存 → 拆复用」四步走。第一步换数据源把load_data里的pd.read_csv换成读你的数据库或接口注意保持返回类型是 DataFrame后面的图表代码就不用动。第二步调交互把侧边栏的筛选控件换成你业务里真正要筛的字段st.selectbox的选项列表从数据里动态取别写死。第三步加缓存凡是读盘、请求、模型推理全部套st.cache_data或st.cache_resource这是 Streamlit 应用流畅度的命门。第四步拆复用如果你要维护多个应用把公共的加载、样式、鉴权逻辑抽到utils/用 2.3 节的方式导入。改造时有个验证习惯值得养成每改完一个函数先在脚本里用st.write把中间结果打出来看确认数据形状和内容对了再接图表。Streamlit 的热重跑让这个验证循环特别快别跳过。另外如果你要把应用部署到服务器给团队用记得在入口加一层简单的密码校验用st.session_state存登录态别裸奔。我早期做过一个内部工具图省事没加鉴权结果被同网段的人扫到端口数据全暴露了从那以后我每次部署前都强制走一遍「端口 鉴权 缓存」三件套检查。希望这个拆解能帮你把手里那堆 Python 脚本变成真正有人愿意点开用的东西。本文还有配套的精品资源点击获取