简介这份资源是围绕 Streamlit 开源库整理的示例网站集合面向希望快速上手数据可视化与交互式 Web 应用开发的数据科学从业者、Python 学习者及工程师。Streamlit 以“代码即文档”为核心理念让开发者无需深入前端即可用 Python 定义布局与功能并支持 Pandas、NumPy、Plotly 等常用数据处理与可视化库。压缩包共 7 个文件包含 2 个 py 脚本、3 张 jpg 图片、1 个 txt 与 1 个 md 文档整体约 518KB脚本用于定义应用结构与交互逻辑图片与文本则辅助演示和说明。目前已有 2719 人学习下载。通过研究其中的示例应用与自定义组件读者可以掌握应用入口组织、数据导入清洗、图表集成、按钮滑块下拉菜单等交互元素添加以及容器布局控制与多平台部署思路从而提升数据应用开发能力。1. 用 Python 把数据脚本变成可交互网站streamlit 项目集合拆解很多人写 Python 做数据分析最后卡在“怎么给别人看”这一步。Jupyter Notebook 自己跑得挺爽发给同事就变成一堆看不懂的单元格用 Flask 或 Django 搭个页面光路由、模板、前端联调就能耗掉一整天。这个项目集合走的是另一条路用 streamlit 把 Python 脚本直接变成网页应用不用写 HTML、不用配路由一个streamlit run就能在浏览器里打开。它适合两类人一类是手里有数据处理逻辑、想快速做个可视化界面给自己或团队用的开发者另一类是想学 streamlit 但不知道从哪下手的人直接拿现成的页面改比看文档快得多。整个集合覆盖了从单页工具到多页应用的常见形态下面按“能干什么、怎么跑、怎么改”的顺序拆一遍。2. 项目定位与技术选型为什么是 streamlit 而不是 Flask2.1 这个集合到底包含什么从标题就能看出来这不是一个单一应用而是一组用 streamlit 写的网站示例的集合。每个子目录通常对应一个独立可运行的页面或小应用彼此之间共享同一套 Python 环境。常见的形态包括数据上传与预览页、参数调节与实时图表页、多页导航应用、以及带缓存的计算密集型页面。这种组织方式的好处是你不需要理解一个庞大工程的启动流程挑一个目录进去就能跑坏处是依赖可能分散在各个子项目里需要自己确认版本。我一般会把这类集合当成“模板库”来用要做数据看板就找带图表和筛选的那个要做文件处理工具就找带上传和下载的那个。比起从零写st.session_state和布局复制一个能跑的骨架再改业务逻辑效率高很多。2.2 技术栈与运行依赖核心依赖只有几个依赖作用常见版本要求Python运行环境3.8 及以上streamlit把脚本转成 Web 应用1.xpandas表格与数据处理1.x / 2.xnumpy数值计算1.xmatplotlib / plotly图表渲染按子项目而定streamlit 的工作模型和传统 Web 框架完全不同。它没有显式的路由定义脚本从上到下执行一次就是一次页面渲染用户任何交互点按钮、拖滑块都会触发整个脚本重新执行。理解这一点很关键否则你会奇怪为什么变量在交互后“丢了”。实际上不是丢了是脚本重跑了需要用st.session_state来保存跨交互的状态。2.3 和 Flask 路线的差别Flask 需要你定义 URL、写视图函数、准备模板前后端职责分明但代码量大。streamlit 把这些都省了代价是控制粒度粗你很难做复杂的页面跳转动画也不容易精细控制 DOM。对于内部工具、数据看板、原型验证这个代价完全可以接受对于面向公众的复杂产品可能就不太合适。这个集合里的项目基本都属于前者定位很清晰。3. 跑起来环境准备与启动流程3.1 获取代码与目录确认拿到项目后先别急着装依赖先看一眼目录结构。典型的集合会长这样streamlit-projects/ ├── app_basic/ │ └── main.py ├── app_data_viewer/ │ ├── main.py │ └── requirements.txt ├── app_multipage/ │ ├── main.py │ └── pages/ │ ├── 1_upload.py │ └── 2_charts.py └── README.md每个子目录是一个独立入口。pages/目录是 streamlit 的多页应用约定放在里面的.py文件会自动出现在侧边栏导航中文件名前缀数字决定排序。确认你要跑的是哪一个再进对应目录。3.2 创建虚拟环境并安装依赖强烈建议用虚拟环境避免和系统里的包打架# 创建虚拟环境 python -m venv venv # 激活Linux / macOS source venv/bin/activate # 激活Windows venv\Scripts\activate # 安装核心依赖 pip install streamlit pandas numpy如果子目录里有requirements.txt优先用它pip install -r requirements.txt这里有个血泪经验streamlit 版本差异会导致部分 API 行为不同比如st.experimental_rerun在新版本里改成了st.rerun。如果跑起来报AttributeError先检查版本别急着改业务代码。3.3 启动应用与访问在子项目目录下执行streamlit run main.py终端会输出一个本地地址默认是http://localhost:8501浏览器打开就能看到页面。如果端口被占用可以指定streamlit run main.py --server.port 8600想让同网络的其他人访问加上streamlit run main.py --server.address 0.0.0.0注意开放到 0.0.0.0 之前确认网络环境可信内部工具不要随意暴露到公网。启动后如果页面空白或报错先看终端日志streamlit 的异常堆栈会直接打在那里比浏览器控制台清楚得多。4. 核心模块拆解从脚本到页面的关键代码4.1 页面布局与组件调用streamlit 的页面就是一系列组件调用按顺序堆叠。下面是一个典型的数据预览页骨架import streamlit as st import pandas as pd # 页面标题会显示在浏览器标签和页面顶部 st.title(数据预览工具) # 文件上传组件返回一个类文件对象 uploaded st.file_uploader(选择 CSV 文件, type[csv]) if uploaded is not None: # 读取上传的文件注意这里直接用对象不需要落盘 df pd.read_csv(uploaded) # 侧边栏放筛选控件主区域放结果 st.sidebar.header(筛选条件) cols st.sidebar.multiselect(选择列, df.columns.tolist(), defaultdf.columns.tolist()) # 展示前若干行 st.subheader(数据预览) st.dataframe(df[cols].head(50)) # 简单统计 st.subheader(描述性统计) st.write(df[cols].describe())逻辑说明st.file_uploader返回的是内存中的文件对象pd.read_csv可以直接读省去了保存临时文件的步骤。st.sidebar把控件放到左侧栏主区域留给结果这是 streamlit 里最常见的布局分工。st.dataframe渲染的是可交互表格支持排序和缩放比st.table更适合大数据量。参数方面type[csv]限制上传格式可以改成[csv, xlsx]支持 Excel但读取时要换成pd.read_excel。head(50)控制预览行数数据量大时不要直接st.dataframe(df)否则页面会卡。4.2 状态管理与缓存前面说过每次交互脚本都会重跑。如果有个耗时计算不加缓存就会每次交互都算一遍体验很差。streamlit 提供了两个装饰器import streamlit as st import pandas as pd import time # 缓存数据加载相同参数只执行一次 st.cache_data def load_data(path: str) - pd.DataFrame: time.sleep(2) # 模拟耗时读取 return pd.read_csv(path) # 缓存资源对象适合数据库连接、模型等不可序列化的东西 st.cache_resource def get_connection(): return create_db_connection() df load_data(data.csv)st.cache_data适合返回 DataFrame、字典这类可序列化数据它会根据函数参数做缓存键。st.cache_resource适合返回连接、模型这类全局共享对象。用错的话会出现“缓存不生效”或“对象被重复创建”的问题。跨交互保存状态则用st.session_state# 初始化计数器只在第一次运行时设置 if count not in st.session_state: st.session_state.count 0 if st.button(加一): st.session_state.count 1 st.write(f当前计数{st.session_state.count})这里的关键是初始化判断。如果不判断直接赋值每次重跑都会把计数清零按钮就“失灵”了。这是新手最容易翻车的地方。4.3 多页应用与导航多页应用靠pages/目录约定实现不需要写路由代码。主入口main.py里可以放首页内容pages/下的文件自动成为子页面# main.py import streamlit as st st.title(首页) st.write(从左侧选择功能页面) # pages/1_upload.py import streamlit as st st.title(上传页面) file st.file_uploader(上传文件)侧边栏会自动生成导航文件名1_upload.py显示为“Upload”数字控制顺序。如果想自定义页面名称可以在文件顶部用st.set_page_config配合或者直接用中文文件名注意编码问题。这种约定式路由省事但页面间的数据共享要靠st.session_state或缓存函数不能靠模块级变量。5. 避坑与常见问题排查5.1 页面反复重跑导致状态丢失现象点一次按钮之前输入的内容全没了。原因streamlit 每次交互都重跑脚本普通变量不跨运行保留。解决所有需要跨交互保留的值都放进st.session_state并在首次运行时初始化。判断依据是“这个值在用户下一次点击后还需要吗”需要就存。5.2 缓存不生效或报不可哈希错误现象加了st.cache_data但函数还是每次执行或者直接报UnhashableParamError。原因缓存键依赖参数如果传入了 DataFrame、自定义对象这类不可哈希参数缓存无法建立。解决把不可哈希参数转成可哈希形式比如传文件路径而不是文件对象传列名列表的元组而不是列表。必要时用st.cache_resource替代。5.3 大数据量页面卡顿现象上传几万行数据后页面响应很慢拖动滑块一卡一卡。原因每次交互都重新读取和渲染全量数据。解决读取用st.cache_data缓存展示用st.dataframe(df.head(N))限制行数筛选逻辑尽量在缓存后的数据上做。图表同理不要每次重算全量聚合。5.4 端口占用或启动后无法访问现象streamlit run报端口被占用或者浏览器打不开。原因默认 8501 端口被其他进程占用或服务只绑定了本地回环地址。解决换端口--server.port 8600需要外部访问时加--server.address 0.0.0.0同时确认防火墙放行。启动日志里会打印实际监听地址以日志为准。5.5 依赖版本冲突现象代码里用的 API 在当前版本不存在报AttributeError或ImportError。原因streamlit 迭代快部分实验性 API 会改名或移除。解决先pip show streamlit看版本对照官方变更说明调整调用或者按子项目的requirements.txt锁定版本。不要盲目升级到最新版先确认代码兼容。6. 二次开发把示例改成自己的工具拿到这个集合后最有价值的用法不是逐个跑一遍而是挑一个最接近你需求的页面把业务逻辑替换掉。我通常按这个顺序改先改数据来源把示例里的pd.read_csv(data.csv)换成你的数据库查询或 API 调用再改交互控件把不需要的筛选去掉加上你需要的参数最后调布局用st.columns做左右分栏把结果和控件分开。改造时有个技巧值得单独说把业务逻辑抽成纯函数和 streamlit 组件调用分离。比如# 业务逻辑不依赖 streamlit方便单测 def compute_metrics(df: pd.DataFrame, threshold: float) - pd.DataFrame: filtered df[df[value] threshold] return filtered.groupby(category).agg({value: mean}).reset_index() # 页面层只负责拿输入、调函数、展示结果 threshold st.slider(阈值, 0.0, 100.0, 50.0) result compute_metrics(df, threshold) st.dataframe(result)这样改业务时不用动页面代码测逻辑时也不用启动 streamlit。验证方法很简单先在本地用pytest跑纯函数确认数值正确再启动页面看交互。两边分开排查比混在一起调试快得多。另一个常被忽略的点是配置。streamlit 支持.streamlit/config.toml来设置主题、端口、上传大小限制等[server] maxUploadSize 200 [theme] primaryColor #1f77b4把配置写进文件比每次命令行传参可靠也方便团队共享。上传大文件时如果不改maxUploadSize默认 200MB 可能不够用户会看到上传失败但不知道原因。从那以后我每次改这类项目都强制先把业务逻辑抽出来单独验证一遍再回到页面层调交互。页面问题十有八九是状态或缓存引起的逻辑问题十有八九是数据或参数引起的分开看能省不少时间。希望帮到你。本文还有配套的精品资源点击获取