Article

模型可视化 Streamlit 速查文档

更新于：2026-07-20

第1章：初识 Streamlit

1.1 什么是 Streamlit

概念名称说明注意事项
Streamlit一个开源的 Python 库，用于快速构建和共享数据可视化 Web 应用。开发者只需编写纯 Python 脚本即可生成交互式网页，无需前端知识（如 HTML、CSS、JavaScript）。Streamlit 适用于快速原型开发和内部工具构建，不适合高并发或复杂用户权限系统的生产级应用。
应用本质每个 Streamlit 应用本质上是一个 Python 脚本，从上到下逐行执行，每次用户交互或代码变更都会重新运行整个脚本。理解”全脚本重运行”机制是掌握 Streamlit 行为的关键，避免在循环中放置昂贵操作。
目标用户数据科学家、机器学习工程师、分析师等希望快速将数据分析结果转化为交互式界面的 Python 开发者。不适合需要精细控制 UI 布局或复杂路由逻辑的 Web 开发者。

1.2 Streamlit 的核心特点与适用场景

特点/场景说明注意事项
极简开发只需 Python 基础，调用 st.xxx() 函数即可添加 UI 元素，无需前端知识。UI 定制能力有限，高级样式需借助 CSS 或自定义组件。
实时重载修改代码后保存，浏览器自动刷新并显示最新效果，极大提升开发效率。频繁重运行可能影响性能，建议使用缓存优化。
内置组件丰富提供文本、图表、控件、布局等多种开箱即用的组件。部分高级图表需集成 Matplotlib、Plotly 等第三方库。
会话状态支持通过 st.session_state 实现跨重运行的状态保持。必须正确初始化状态键，否则可能引发 KeyError。
适用场景：数据展示快速将 Pandas DataFrame、统计图表可视化为 Web 页面。大数据集需分页或懒加载，避免阻塞主线程。
适用场景：模型演示构建机器学习模型的交互式 Demo，支持参数调节和结果展示。模型加载应使用 @st.cache_resource 避免重复加载。
适用场景：内部工具创建数据标注、配置管理、报告生成等团队内部小工具。不推荐用于公开暴露的高安全要求系统。

1.3 安装与环境配置

操作步骤操作细节注意事项
安装 Streamlit在命令行执行：pip install streamlit建议在虚拟环境中安装以避免依赖冲突。
验证安装执行：streamlit hello，此命令启动内置示例应用。若命令未找到，请检查 Python Scripts 目录是否在系统 PATH 中。
创建项目目录新建文件夹作为项目根目录，例如：my_streamlit_app保持项目结构清晰，便于后续部署。
初始化虚拟环境（可选）进入项目目录，执行：python -m venv venv；激活环境（Windows）：venv\Scripts\activate；激活环境（macOS/Linux）：source venv/bin/activate使用虚拟环境可隔离依赖，推荐生产项目使用。
安装其他依赖根据需要安装 pandas、numpy、matplotlib 等库：pip install pandas matplotlib将依赖记录到 requirements.txt 以便部署。
创建 requirements.txt执行：pip freeze > requirements.txt部署到云端时必须提供此文件。

第2章：第一个 Streamlit 应用

2.1 创建第一个 .py 脚本

操作步骤操作细节注意事项
新建 Python 文件在项目目录中创建 app.py（或其他名称）。文件扩展名必须为 .py。
编写基础代码输入以下内容：必须导入 streamlit 模块，通常简写为 st。
添加标题可加入：st.title("我的第一个应用")标题将显示在页面顶部，增强可读性。
保存文件使用文本编辑器或 IDE 保存 app.py。确保编码为 UTF-8，避免中文乱码。
代码组织建议按”导入 → 配置 → 主内容 → 侧边栏”顺序组织代码。保持逻辑清晰，便于维护。
import streamlit as st
st.write("Hello, Streamlit!")

2.2 运行应用：streamlit run

方法名称语法用途代码示例注意事项
streamlit runstreamlit run [filename].py启动指定的 Streamlit 脚本并打开本地 Web 服务器。streamlit run app.py确保当前目录包含该文件，或提供完整路径。
查看帮助streamlit run --help显示 run 命令的所有可选参数。streamlit run --help可查看 --server.port、--server.address 等高级选项。
指定端口streamlit run app.py --server.port 8501自定义应用运行端口（默认 8501）。streamlit run app.py --server.port 8501若端口被占用，可更换为其他如 8502。
指定主机streamlit run app.py --server.address 0.0.0.0允许外部设备访问（如云服务器）。streamlit run app.py --server.address 0.0.0.0仅在必要时开放，注意网络安全。

2.3 热重载（Hot Reload）机制

概念名称说明注意事项
热重载（Hot Reload）当应用运行时，修改并保存 Python 脚本，Streamlit 会自动检测文件变化并重新运行脚本，浏览器同步刷新。是开发阶段的核心特性，极大提升迭代效率。
触发条件保存 .py 文件（Ctrl+S 或等效操作）。仅监控主脚本及其直接导入的模块（若启用 watchdog）。
重运行范围整个脚本从头到尾重新执行。所有变量状态丢失，需用 st.session_state 持久化数据。
状态保留st.session_state 中的值在重运行间保持不变。必须先检查键是否存在再访问，避免异常。
性能提示对于耗时操作（如数据加载），应使用 @st.cache_data 装饰器避免重复执行。缓存基于输入参数和函数体内容，自动管理。
禁用热重载启动时加 --global.developmentMode false 参数。一般不建议关闭，仅用于特定调试场景。

第3章：基础文本与数据展示

3.1 标题、文本与 Markdown：st.title, st.header, st.subheader, st.text, st.markdown

方法名称语法用途代码示例注意事项
st.titlest.title(body, anchor=None, help=None)显示主标题，样式最大。st.title("我的应用")通常用于页面顶部，一个页面建议仅一个主标题。
st.headerst.header(body, anchor=None, help=None)显示一级标题，小于 title。st.header("数据概览")可用于分节标题，支持 help 提示。
st.subheaderst.subheader(body, anchor=None, help=None)显示二级标题，小于 header。st.subheader("用户信息", help="这是用户数据部分")help 参数显示小问号提示图标。
st.textst.text(body)原样显示字符串，保留空格和换行。st.text("Hello\\nWorld") 输出两行文本。不解析 Markdown，适合显示代码或日志。
st.markdownst.markdown(body, unsafe_allow_html=False)渲染 Markdown 格式文本。st.markdown("**加粗** 和 *斜体*")；st.markdown("# 一级标题")unsafe_allow_html=True 允许嵌入 HTML，但有安全风险，慎用。

3.2 展示数据：st.write, st.dataframe, st.table

方法名称语法用途代码示例注意事项
st.writest.write(*args, **kwargs)通用写入方法，自动推断内容类型并渲染。st.write("文本")；st.write(df)（df 为 DataFrame）；st.write(plt.gcf())（图表）最常用，功能最灵活，可替代多数 st.xxx 调用。
st.dataframest.dataframe(data=None, width=None, height=None, use_container_width=False)显示可滚动的交互式数据表。st.dataframe(df, height=200)支持排序、列宽调整，适合大数据集（>50 行）。
st.tablest.table(data=None)显示静态表格，完整渲染所有数据。st.table(df.head(10))不可滚动，一次性加载全部内容，适合小数据集（<50 行）。

3.3 展示 JSON 与字典：st.json

方法名称语法用途代码示例注意事项
st.jsonst.json(body=None, expanded=True)美化显示 JSON 或字典数据，支持折叠展开。st.json({"name": "Alice", "age": 30})；st.json(data, expanded=False)expanded=False 时默认折叠，点击展开；适合查看嵌套结构。

第4章：控件与用户输入

4.1 文本输入：st.text_input, st.text_area

方法名称语法用途代码示例注意事项
st.text_inputst.text_input(label, value="", max_chars=None, key=None, type="default", help=None, autocomplete=None, on_change=None, args=None, kwargs=None)单行文本输入框。name = st.text_input("姓名", "请输入姓名")；if name: st.write(f"你好，{name}")value 为默认值；key 用于状态管理；on_change 回调在值改变时触发。
st.text_areast.text_area(label, value="", height=None, max_chars=None, key=None, help=None, on_change=None, args=None, kwargs=None)多行文本输入区域。feedback = st.text_area("意见", height=100)height 控制高度（像素）；适合长文本输入如反馈、代码等。

4.2 数值输入：st.number_input

方法名称语法用途代码示例注意事项
st.number_inputst.number_input(label, min_value=None, max_value=None, value=None, step=None, format=None, key=None, help=None, on_change=None, args=None, kwargs=None)输入数字，支持步长和范围限制。age = st.number_input("年龄", 0, 120, 25, 1)；price = st.number_input("价格", 0.0, 1000.0, 99.9, 0.5)value 可为 int 或 float；step 决定增减步长；format 控制显示格式如 %.2f。

4.3 滑块输入：st.slider, st.select_slider

方法名称语法用途代码示例注意事项
st.sliderst.slider(label, min_value=None, max_value=None, value=None, step=None, format=None, key=None, help=None, on_change=None, args=None, kwargs=None)滑动条选择数值或日期。score = st.slider("评分", 0, 10, 5)；date_range = st.slider("日期范围", start, end, (start+timedelta(days=7), end))value 可为单值或元组（范围选择）；支持 datetime 类型。
st.select_sliderst.select_slider(label, options=[], value=None, format_function=None, key=None, help=None, on_change=None, args=None, kwargs=None)在预设选项中滑动选择。color = st.select_slider("颜色", options=["红","黄","蓝"], value="黄")options 必须为列表；不可输入新值，仅限选项内选择。

4.4 选择类控件：st.selectbox, st.multiselect

方法名称语法用途代码示例注意事项
st.selectboxst.selectbox(label, options, index=0, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None)下拉框单选。fruit = st.selectbox("水果", ["苹果","香蕉","橙子"])index 设置默认选中项索引（从 0 开始）；返回选中的值。
st.multiselectst.multiselect(label, options, default=None, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None)多选框，可选多个。colors = st.multiselect("颜色", ["红","绿","蓝"], default=["红"])default 为列表，指定默认选中项；返回选中值的列表。

4.5 布尔输入：st.checkbox, st.radio

方法名称语法用途代码示例注意事项
st.checkboxst.checkbox(label, value=False, key=None, help=None, on_change=None, args=None, kwargs=None)复选框，返回 True/False。agree = st.checkbox("我同意条款")；if agree: st.write("已同意")value 设置初始状态；常用于条件开关。
st.radiost.radio(label, options, index=0, format_func=None, key=None, help=None, on_change=None, args=None, kwargs=None)单选按钮组。level = st.radio("难度", ("简单","中等","困难"))index 设置默认选项索引；返回选中的值。

4.6 文件上传：st.file_uploader

方法名称语法用途代码示例注意事项
st.file_uploaderst.file_uploader(label, type=None, accept_multiple_files=False, key=None, help=None, on_change=None, args=None, kwargs=None)上传文件，返回 UploadedFile 对象。uploaded_file = st.file_uploader("上传CSV")；if uploaded_file: df = pd.read_csv(uploaded_file)type 限制文件类型如 ["csv", "xlsx"]；accept_multiple_files=True 允许多选；大文件可能超时。

4.7 日期与时间输入：st.date_input, st.time_input

方法名称语法用途代码示例注意事项
st.date_inputst.date_input(label, value=None, min_value=None, max_value=None, key=None, help=None, on_change=None, args=None, kwargs=None)选择日期，返回 datetime.date 对象。start_date = st.date_input("开始日期", datetime.now().date())value 可为 date 对象或 None（默认今天）；支持 min/max 限制范围。
st.time_inputst.time_input(label, value=None, key=None, help=None, on_change=None, args=None, kwargs=None)选择时间，返回 datetime.time 对象。alarm_time = st.time_input("闹钟时间", None)value 可为 time 对象或 None（默认午夜 00:00）。

第5章：按钮与状态管理

5.1 按钮：st.button

方法名称语法用途代码示例注意事项
st.buttonst.button(label, key=None, help=None, on_click=None, args=None, kwargs=None)创建可点击按钮，返回布尔值表示是否被点击。if st.button("点击我"): st.write("按钮被点击了！")每次点击后返回 True 一次，下次重运行即变为 False（瞬时状态）；key 用于区分多个按钮。

5.2 会话状态（Session State）基础

概念名称说明注意事项
Session StateStreamlit 为每个用户浏览器会话维护的字典式对象，用于在脚本重运行之间持久化数据。类似于 Web 应用中的 session，但作用域限于单个用户会话。
状态生命周期从用户打开应用开始创建，关闭浏览器或超时后销毁。不同用户拥有独立的状态空间，互不干扰。
状态用途存储用户输入、表单数据、模型参数、临时结果等需跨交互保留的信息。避免存储大量数据（如整个 DataFrame），影响性能。
状态访问方式通过 st.session_state 对象以属性或键值方式访问：
st.session_state.name 或 st.session_state["name"]		访问前必须确保键已存在，否则抛出 AttributeError 或 KeyError。

5.3 使用 st.session_state 管理状态

操作类型操作细节注意事项
初始化状态在访问前检查并初始化：
if 'count' not in st.session_state:
st.session_state.count = 0		必须在使用前初始化，常见模式是用 if 判断键是否存在。
更新状态直接赋值：st.session_state.count += 1；或使用 lambda 函数绑定到 on_click：
st.button("加1", on_click=lambda: st.session_state.update(count=st.session_state.count+1))		赋值操作在当前重运行中立即生效。
删除状态使用 del 语句：del st.session_state.key_name删除后键不存在，再次访问需重新初始化。
批量更新使用 update 方法：st.session_state.update({'a': 1, 'b': 2})可一次性设置多个键值对。
状态回调在控件中使用 on_change 参数指定回调函数，当值改变时执行。回调函数应在定义时就声明，避免在循环中创建。

第6章：图表与可视化集成

6.1 使用 st.pyplot 展示 Matplotlib 图表

方法名称语法用途代码示例注意事项
st.pyplotst.pyplot(fig=None, clear_figure=False, **kwargs)显示 Matplotlib 图形对象。fig, ax = plt.subplots()
ax.plot([1,2,3], [1,4,2])
st.pyplot(fig)		fig 为 Figure 对象；clear_figure=True 在显示后清空图形释放内存；建议每次创建新 fig 避免重用。
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 2])
st.pyplot(fig)

6.2 使用 st.plotly_chart 展示 Plotly 图表

方法名称语法用途代码示例注意事项
st.plotly_chartst.plotly_chart(figure_or_data, width=None, height=None, use_container_width=False, sharing="streamlit", theme="streamlit", **kwargs)显示 Plotly 交互式图表。fig = px.line(x=[1,2,3], y=[1,4,2])
st.plotly_chart(fig, use_container_width=True)		支持高度交互（缩放、下载、悬停）；theme 控制主题（“streamlit” 或 None）；use_container_width=True 自适应容器宽度。
import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[1, 4, 2])
st.plotly_chart(fig, use_container_width=True)

6.3 使用 st.altair_chart 展示 Altair 图表

方法名称语法用途代码示例注意事项
st.altair_chartst.altair_chart(chart, use_container_width=False, theme="streamlit", **kwargs)显示 Altair 声明式图表。chart = alt.Chart(df).mark_circle().encode(x='x', y='y')
st.altair_chart(chart, use_container_width=True)		Altair 基于 Vega-Lite，语法简洁；theme 控制样式；需确保 df 符合 Altair 要求格式。
import altair as alt

chart = alt.Chart(df).mark_circle().encode(x='x', y='y')
st.altair_chart(chart, use_container_width=True)

6.4 使用 st.vega_lite_chart 展示 Vega-Lite 图表

方法名称语法用途代码示例注意事项
st.vega_lite_chartst.vega_lite_chart(data=None, spec=None, use_container_width=False, theme="streamlit", **kwargs)直接渲染 Vega-Lite 规范（JSON）图表。见下方代码示例适用于直接使用 Vega-Lite JSON 规范的场景；灵活性高但需熟悉 Vega-Lite 语法。
spec = {
    "mark": "bar",
    "encoding": {
        "x": {"field": "a"},
        "y": {"field": "b"}
    }
}
st.vega_lite_chart(df, spec)

6.5 内置图表：st.line_chart, st.bar_chart, st.area_chart

方法名称语法用途代码示例注意事项
st.line_chartst.line_chart(data=None, x=None, y=None, width=0, height=0, use_container_width=True)快速绘制折线图。st.line_chart(df, x="date", y="sales")简化版图表，适合快速原型；自动处理时间序列；功能有限，复杂需求用 Plotly。
st.bar_chartst.bar_chart(data=None, x=None, y=None, width=0, height=0, use_container_width=True)快速绘制柱状图。st.bar_chart(df, x="category", y="value")默认垂直柱状图；支持多系列；x 和 y 指定坐标轴字段。
st.area_chartst.area_chart(data=None, x=None, y=None, width=0, height=0, use_container_width=True)快速绘制面积图。st.area_chart(df, y=["sales", "profit"])显示累积趋势；适合展示占比变化。

第7章：页面布局与容器

7.1 列布局：st.columns

方法名称语法用途代码示例注意事项
st.columnsst.columns(spec, *, gap="medium", vertical_alignment=None)创建并排的列容器，用于水平布局。col1, col2 = st.columns(2)
col1.write("左边")
col2.write("右边")
col_a, col_b = st.columns([3, 1])（宽度比 3:1）		spec 可为整数（等宽列数）或列表（相对宽度）；返回列对象列表；内容需写入具体列中。

7.2 扩展器（Expander）：st.expander

方法名称语法用途代码示例注意事项
st.expanderst.expander(label, expanded=False)创建可展开/折叠的内容区域，隐藏非关键信息。with st.expander("查看详情"):
st.write("这里是详细说明...")
st.dataframe(df)		expanded=True 时默认展开；适合放置日志、参数、冗长数据；所有内容在展开时才渲染。

7.3 侧边栏：st.sidebar

方法名称语法用途代码示例注意事项
st.sidebarst.sidebar.<任何 st 方法>()将元素添加到左侧固定侧边栏中。st.sidebar.title("配置")
option = st.sidebar.selectbox("选择图表类型", ["线图", "柱状图"])
st.sidebar.slider("透明度", 0.0, 1.0, 0.5)		用法与 st 前缀完全相同，只需替换为 st.sidebar；常用于放置控件和导航，保持主区整洁。

7.4 容器：st.container

方法名称语法用途代码示例注意事项
st.containerst.container(height=None, border=None)创建可包含多个元素的逻辑容器，支持滚动。with st.container(height=150, border=True):
st.write("项目1")
st.write("项目2")
st.write("项目3")		height 设置像素高度后内容溢出可滚动；border=True 显示边框；不改变布局，仅组织内容。

7.5 空占位符：st.empty

方法名称语法用途代码示例注意事项
st.emptyst.empty()创建一个空占位符，后续可用其 .write() 等方法动态更新内容。placeholder = st.empty()
for i in range(3):
placeholder.write(f"倒计时: {3-i}")
time.sleep(1)
placeholder.success("完成！")		常用于动态内容、进度展示、条件渲染；同一占位符可被多次更新覆盖。
import time

placeholder = st.empty()
for i in range(3):
    placeholder.write(f"倒计时: {3 - i}")
    time.sleep(1)
placeholder.success("完成！")

第8章：媒体与文件输出

8.1 显示图片：st.image

方法名称语法用途代码示例注意事项
st.imagest.image(image, caption=None, width=None, use_column_width="always", clamp=False, channels="RGB", output_format="auto")显示图像文件或 URL。st.image("logo.png", caption="公司Logo", width=200)
st.image("https://example.com/photo.jpg")		image 可为本地路径、URL 或 PIL/Pillow 对象；width 控制显示宽度；use_column_width="auto" 自适应容器。

8.2 播放音频：st.audio

方法名称语法用途代码示例注意事项
st.audiost.audio(data, format="audio/wav", start_time=0)播放音频文件或流。st.audio("music.mp3", format="audio/mp3")
st.audio(audio_bytes, format="audio/wav")		data 可为本地路径、URL 或字节数据；浏览器自动播放需用户交互（如点击按钮）。

8.3 播放视频：st.video

方法名称语法用途代码示例注意事项
st.videost.video(data, format="video/mp4", start_time=0)播放视频文件或流。st.video("demo.mp4", format="video/mp4")
st.video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")		支持 YouTube 等平台链接；format 指定 MIME 类型；同样受浏览器自动播放策略限制。

8.4 下载链接：st.download_button

方法名称语法用途代码示例注意事项
st.download_buttonst.download_button(label, data, file_name=None, mime=None, key=None, help=None, on_click=None, args=None, kwargs=None)创建下载按钮，允许用户下载数据。见下方代码示例data 可为字符串或字节；mime 指定文件类型（如 “text/csv”, “application/pdf”）；每次点击生成新下载。
csv = df.to_csv(index=False)
st.download_button(
    label="下载CSV",
    data=csv,
    file_name="data.csv",
    mime="text/csv"
)

第9章：进度与状态提示

9.1 进度条：st.progress

方法名称语法用途代码示例注意事项
st.progressst.progress(value, text=None)显示一个进度条，value 为 0.0 到 1.0 之间的浮点数。见下方代码示例value 必须在 [0.0, 1.0] 范围内；常与循环结合使用；需保留返回的占位符对象以更新进度。
import time

my_bar = st.progress(0)
for percent_complete in range(100):
    time.sleep(0.01)
    my_bar.progress(percent_complete + 1)

9.2 弹出提示：st.toast（Streamlit 1.23+）

方法名称语法用途代码示例注意事项
st.toastst.toast(body, icon=None)在屏幕右上角显示短暂的 Toast 通知（持续约 4 秒）。st.toast("任务完成！", icon="🎉")
st.toast("正在处理...")		仅支持 Streamlit 1.23 及以上版本；icon 可为 emoji 或单字符；适合轻量级状态反馈。

9.3 错误、警告、信息提示：st.error, st.warning, st.info, st.success

方法名称语法用途代码示例注意事项
st.errorst.error(body, icon=None)显示红色错误消息。st.error("文件未找到！")用于异常或验证失败场景；icon 可自定义。
st.warningst.warning(body, icon=None)显示黄色警告消息。st.warning("数据可能不完整")提示潜在问题，非致命错误。
st.infost.info(body, icon=None)显示蓝色信息消息。st.info("这是使用说明")提供帮助信息或状态说明。
st.successst.success(body, icon=None)显示绿色成功消息。st.success("数据保存成功！")表示操作成功完成。

9.4 加载动画：st.spinner

方法名称语法用途代码示例注意事项
st.spinnerst.spinner(text="Loading...")在代码块执行期间显示加载动画。见下方代码示例用于包裹耗时操作；提升用户体验；动画在块结束或异常时自动消失。
with st.spinner("正在加载数据..."):
    time.sleep(2)
    df = load_large_data()
    st.success("加载完成")

9.5 日志输出：st.echo

方法名称语法用途代码示例注意事项
st.echost.echo(code_type="python")捕获并显示代码块本身及其执行结果。见下方代码示例code_type 默认为 “python”；适合教学或展示代码逻辑；显示顺序：代码 → 输出。
with st.echo():
    def greet(name):
        return f"Hello {name}"
    st.write(greet("Alice"))

第10章：高级功能与性能优化

10.1 缓存机制：@st.cache_data, @st.cache_resource

方法名称语法用途代码示例注意事项
@st.cache_data@st.cache_data(ttl=None, max_entries=None, persist=None, show_spinner=True, experimental_allow_widgets=False)缓存函数的返回值（如数据、计算结果），避免重复执行。见下方代码示例基于输入参数和函数代码哈希判断是否缓存命中；适合缓存数据或轻量级对象；ttl 设置生存时间（秒）。
@st.cache_resource@st.cache_resource(ttl=None, max_entries=None, persist=None, show_spinner=True)缓存全局资源（如模型、数据库连接），避免重复加载。见下方代码示例缓存对象在所有会话间共享；适合大型、昂贵的资源；不能缓存依赖会话状态的对象。
# cache_data 示例
@st.cache_data
def load_data():
    return pd.read_csv("large.csv")

df = load_data()

# cache_resource 示例
@st.cache_resource
def load_model():
    return pickle.load(open("model.pkl", "rb"))

model = load_model()

10.2 页面跳转与多页面应用（Multipage Apps）

操作步骤操作细节注意事项
创建页面目录在项目根目录创建 pages/ 文件夹。文件夹名称必须为 pages，大小写敏感。
添加页面脚本在 pages/ 内创建多个 .py 文件，如 home.py、data.py、charts.py。文件名决定菜单顺序（按字母排序）；主页面（如 app.py）也会出现在菜单中。
页面内容组织每个页面脚本独立编写，包含自己的 st 元素和逻辑。避免在多个页面重复加载相同资源，可提取到公共模块。
共享状态与数据使用 st.session_state 在页面间传递数据。页面跳转会重新运行目标脚本，注意状态初始化逻辑。
导航机制Streamlit 自动生成侧边栏导航菜单。无法自定义菜单样式或实现编程式跳转（如 st.redirect），需用户手动点击。

10.3 自定义组件（Component）简介

概念名称说明注意事项
自定义组件允许开发者使用 JavaScript、React 等前端技术创建 Streamlit 无法直接提供的 UI 组件。适用于高级用户，需前端开发知识。
实现方式通过 streamlit.components.v1 模块的 declare_component 或 html/iframe 方法嵌入。html 和 iframe 适合简单嵌入；declare_component 支持双向通信。
用途场景集成复杂图表库（如 Three.js）、地图（如 Mapbox）、富文本编辑器等。增加项目复杂度，影响可移植性；调试较困难。
社区组件访问 Streamlit Community Cloud 或 GitHub 查找他人开发的组件。使用前评估安全性与维护状态。

第11章：部署与分享

11.1 部署到 Streamlit Community Cloud

操作步骤操作细节注意事项
注册账号访问 https://streamlit.io/cloud 并使用 GitHub 账号登录。免费计划支持公开应用，私有应用需付费订阅。
连接 GitHub 仓库在 Streamlit Cloud 仪表板中点击”New app”，选择关联的 GitHub 组织和仓库。仓库必须为公开或已授权；支持私有仓库（Pro 及以上计划）。
配置部署参数设置以下字段：
- App location: 主脚本路径（如 app.py）
- Python version: 选择 Python 版本（如 3.9）
- Requirements file: requirements.txt 路径		确保主脚本位于项目根目录或正确填写相对路径。
启动部署点击”Deploy”按钮，Cloud 将自动克隆仓库、安装依赖并启动应用。首次部署可能需要几分钟；后续推送代码会自动触发重新部署（需启用自动同步）。
查看日志在应用详情页查看构建和运行日志，排查错误。常见问题包括依赖缺失、脚本路径错误、端口绑定失败等。
分享应用部署成功后生成唯一 URL（如 your-app.streamlit.app），可直接分享。可设置应用标题、图标和描述以美化展示。

11.2 配置 requirements.txt 与 streamlit_app.py

文件/概念操作细节注意事项
requirements.txt在项目根目录创建该文件，列出所有 Python 依赖及其版本。必须包含 streamlit；建议固定关键库版本避免兼容问题；可使用 pip freeze > requirements.txt 生成。
主应用脚本命名推荐将主入口脚本命名为 app.py 或 streamlit_app.py。Streamlit Cloud 默认查找 app.py，若使用其他名称需在部署时手动指定。
项目结构示例标准结构：
my_streamlit_app/
├── app.py
├── requirements.txt
├── data/
│ └── dataset.csv
└── utils.py		保持结构清晰；数据文件和模块应与主脚本在同一仓库内。
依赖管理最佳实践使用虚拟环境隔离开发依赖；定期更新并测试 requirements.txt。避免包含开发专用包（如 pytest）；大文件（>1GB）不建议放入仓库，可使用外部链接加载。

示例 requirements.txt：

streamlit==1.27.0
pandas>=1.5.0
numpy==1.24.3
matplotlib
scikit-learn

11.3 环境变量与 secrets 管理

方法/概念语法/操作细节用途代码示例注意事项
secrets.toml（本地）在项目根目录创建 .streamlit/secrets.toml 文件存储本地开发用的敏感信息，不应提交到 GitHub。password = st.secrets["db_password"]
api_key = st.secrets["api_key"]		将 .streamlit/secrets.toml 添加到 .gitignore 文件中。
Secrets 管理界面（Cloud）在 Streamlit Cloud 应用设置中进入”Secrets”标签页，以键值对形式添加环境变量。替代 secrets.toml 用于云端部署，安全存储 API 密钥、数据库密码等。同上：st.secrets["key_name"]云端优先读取控制台配置的 secrets，覆盖本地文件。
访问 Secrets通过 st.secrets 对象以字典方式访问。st.secrets 支持嵌套结构（TOML 表）见下方代码示例访问前确保键存在，可用 if "key" in st.secrets 判断。
使用 os.environ（替代方案）直接使用系统环境变量。适用于非 Streamlit 专属场景；在 Cloud 中也可通过 Secrets 注入环境变量。import os
api_key = os.environ.get("API_KEY")		-

示例 secrets.toml：

[general]
db_password = "my-secret-pass"
api_key = "sk-abc123"

[database]
host = "localhost"
port = 5432