Streamlit 数据应用¶

Streamlit 是 Python 数据应用开发的"神器"，纯 Python 代码写 Web 应用，不需要 HTML/CSS/JS，10 分钟就能把数据分析脚本变成可交互的 Web 仪表盘，被 90% 的财富 50 强公司使用。

核心知识点¶

知识点	说明
工具定位	Python Web 数据应用框架
最新版本	v1.57.0（2026 年 5 月）
核心优势	纯 Python、零前端知识、自动响应式、快速原型
部署方式	Streamlit Community Cloud（免费）或 Docker
适用场景	数据仪表盘、ML 演示、内部工具、报告生成
许可证	Apache 2.0 开源

安装配置¶

# pip 安装
pip install streamlit                  # 安装 Streamlit

# 验证
streamlit hello                        # 运行示例应用

# 启动应用
streamlit run app.py                   # 运行你的应用
streamlit run app.py --server.port 8501  # 指定端口

基本使用¶

1. 第一个 Streamlit 应用¶

# app.py
import streamlit as st                # 导入 Streamlit
import pandas as pd                   # 导入 Pandas

# 标题和描述
st.title("🧬 菌群分析仪表盘")          # 大标题
st.markdown("上传 CSV 文件，自动生成可视化报告")  # 描述

# 侧边栏
st.sidebar.header("设置")              # 侧边栏标题
sample_filter = st.sidebar.selectbox(  # 下拉选择框
    "选择组别",
    ["全部", "健康", "疾病"]
)

# 文件上传
uploaded_file = st.file_uploader(      # 文件上传组件
    "上传丰度表 (CSV)",
    type=["csv", "tsv"]
)

if uploaded_file:
    df = pd.read_csv(uploaded_file)    # 读取上传文件
    st.dataframe(df)                   # 显示交互式表格
    st.line_chart(df.select_dtypes(include='number'))  # 快速折线图

# 运行
streamlit run app.py                   # 浏览器自动打开 http://localhost:8501

2. 常用组件¶

import streamlit as st

# === 输入组件 ===
name = st.text_input("输入样本名")      # 文本输入
age = st.number_input("输入年龄", min_value=0, max_value=150)  # 数值输入
agree = st.checkbox("同意条款")         # 复选框
option = st.selectbox("选择方法", ["Shannon", "Simpson", "Chao1"])  # 下拉选择
values = st.slider("设置阈值", 0.0, 1.0, 0.5)  # 滑块
date = st.date_input("选择日期")        # 日期选择

# === 输出组件 ===
st.write("Hello, World!")              # 万能输出（自动判断类型）
st.metric("Shannon 指数", "3.45", "0.12")  # 指标卡（带变化箭头）
st.json({"key": "value"})              # JSON 显示
st.code("print('Hello')", language="python")  # 代码块
st.latex(r"H' = -\sum p_i \ln p_i")   # LaTeX 公式

# === 布局组件 ===
col1, col2 = st.columns(2)            # 两列布局
with col1:
    st.write("左边内容")
with col2:
    st.write("右边内容")

tab1, tab2 = st.tabs(["数据", "图表"])  # 标签页
with tab1:
    st.dataframe(df)
with tab2:
    st.line_chart(df)

3. 图表展示¶

import streamlit as st
import plotly.express as px            # Plotly 交互式图表
import matplotlib.pyplot as plt        # Matplotlib 静态图

# Plotly 图表（推荐，自动交互）
fig = px.bar(df, x="物种", y="丰度", color="组别")
st.plotly_chart(fig, use_container_width=True)  # 自适应宽度

# Matplotlib 图表
fig, ax = plt.subplots()
ax.bar(df["物种"], df["丰度"])
st.pyplot(fig)                         # 显示 Matplotlib 图

# 内置简易图表
st.bar_chart(df.set_index("物种")["丰度"])   # 内置柱状图
st.line_chart(df)                             # 内置折线图
st.area_chart(df)                             # 内置面积图

高级用法¶

1. 缓存（提升性能的关键）¶

import streamlit as st

# 缓存数据加载（只执行一次，后续直接用缓存）
@st.cache_data                         # 缓存装饰器（数据类的用这个）
def load_data(filepath):
    """加载大数据文件，缓存避免重复读取"""
    return pd.read_csv(filepath)       # 只有第一次会真正读文件

# 缓存模型/连接等资源
@st.cache_resource                     # 缓存装饰器（资源类的用这个）
def load_model():
    """加载 ML 模型，只加载一次"""
    import joblib
    return joblib.load("model.pkl")    # 只加载一次

df = load_data("big_data.csv")         # 自动使用缓存
model = load_model()                   # 自动使用缓存

2. 会话状态（跨页面保持数据）¶

# 会话状态：在用户交互之间保持数据
if "counter" not in st.session_state:  # 初始化
    st.session_state.counter = 0

if st.button("点击计数"):              # 按钮
    st.session_state.counter += 1      # 修改状态

st.write(f"点击次数: {st.session_state.counter}")  # 显示状态

3. 多页面应用¶

# 文件结构：
# app.py                   主入口
# pages/
#   1_数据上传.py           第一页
#   2_数据分析.py           第二页
#   3_可视化.py             第三页

# Streamlit 自动根据 pages/ 目录生成侧边栏导航
# 文件名前的数字控制排序

4. 表单（批量提交）¶

# 表单：用户填完所有内容后一次性提交
with st.form("analysis_form"):        # 创建表单
    sample_id = st.text_input("样本 ID")
    method = st.selectbox("分析方法", ["PCoA", "NMDS", "t-SNE"])
    threshold = st.slider("阈值", 0.0, 1.0, 0.05)

    submitted = st.form_submit_button("开始分析")  # 提交按钮

if submitted:                          # 点击提交后执行
    st.write(f"分析样本 {sample_id}，方法 {method}")
    # 执行分析逻辑...

5. 部署到 Community Cloud（免费）¶

# 1. 代码推送到 GitHub
# 2. 访问 share.streamlit.io
# 3. 选择仓库和 app.py
# 4. 点击 Deploy，几分钟后上线

# requirements.txt（部署需要）
streamlit
pandas
plotly
scikit-learn

常见报错与解决¶

报错信息	原因	解决方法
`DuplicateWidgetID`	相同 key 的组件重复	给每个组件加唯一 `key` 参数
页面一直重新运行	Streamlit 的 rerun 机制	用 `@st.cache_data` 缓存计算
上传文件大小限制	默认 200MB	配置 `server.maxUploadSize`
部署后运行慢	没用缓存	用 `@st.cache_data` 缓存数据加载

速查表¶

# ===== Streamlit 速查表 =====

# 安装运行
pip install streamlit
streamlit run app.py

# 文本
st.title("标题")
st.header("一级标题")
st.subheader("二级标题")
st.write("万能输出")
st.markdown("**Markdown**")
st.code("code", language="python")

# 输入
st.text_input("文本")
st.number_input("数字")
st.selectbox("下拉", options)
st.multiselect("多选", options)
st.slider("滑块", min, max, default)
st.checkbox("复选框")
st.button("按钮")
st.file_uploader("上传")

# 输出
st.dataframe(df)                # 交互式表格
st.metric("指标", "值", "变化")  # 指标卡
st.plotly_chart(fig)            # Plotly 图表
st.pyplot(fig)                  # Matplotlib 图表

# 布局
st.columns(n)                   # 多列
st.tabs(["Tab1", "Tab2"])       # 标签页
st.sidebar                      # 侧边栏
st.expander("展开")             # 可折叠区域

# 缓存
@st.cache_data                  # 缓存数据
@st.cache_resource              # 缓存资源

# 部署
# GitHub → share.streamlit.io → Deploy（免费）