简介：这份资源是面向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 要pandas==1.5，应用 B 要pandas==2.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.path：
import 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_value=0, max_value=120, value=25, step=1) # 下拉选择，返回选中的选项 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_state：
import 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 :lang=zh查系统里有哪些中文字体，填进去。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 脚本，变成真正有人愿意点开用的东西。
本文还有配套的精品资源，点击获取
