Streamlit 中文教程：从一次重跑理解状态和缓存

Streamlit 让 Python 脚本直接输出输入控件、表格、图表、布局和聊天界面。它上手快，但交互后脚本如何重跑、状态保存在哪里、缓存是否跨用户，决定了应用是否正确。

1. 1.64.0 的版本事实

官方在 2026-09-15 发布 1.64.0，对应提交 bab1da9。这一版加入原生 st.echarts_chart、异步感知的 st.cache_data 和 st.cache_resource，还给多个输入组件增加事件选项，并修复重跑、Altair、PyDeck 和 Custom Components v2 的问题。包要求 Python 3.10 以上。

2. 浏览器事件为什么会重跑脚本

streamlit run 启动 Python 服务，浏览器通过 WebSocket 建立会话。脚本执行时，st.* 命令把页面变化发给前端。用户改变滑块或输入框后，事件返回服务器，框架通常从上到下再执行一次脚本。

因此，发送邮件、扣款、写文件等副作用不能放在每次都会走到的顶层代码里。按钮回调也需要幂等设计。能缩小到 fragment 的交互不要重跑整个应用。

3. 安装固定版本并启动最小应用

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "streamlit==1.64.0"
python -m pip freeze > requirements.lock.txt

新建 app.py：

import streamlit as st

st.title("重跑观察")
st.session_state.setdefault("runs", 0)
st.session_state.runs += 1

x = st.slider("x", 0, 10, 2)
st.write("本会话脚本执行次数", st.session_state.runs)
st.write("x 的平方", x * x)

streamlit run app.py --server.address 127.0.0.1

拖动滑块后执行次数会上升，这能直接看到重跑。不同浏览器会话有各自的 Session State；它不是数据库，也不应保存必须长期存在的业务记录。

4. 两类缓存解决不同问题

用户私有数据不要塞进全局资源缓存。缓存函数还要设置合理 TTL 和清理方式，模型或数据库连接升级时主动失效。

5. 上传、密钥和自定义 HTML

上传文件名、内容、查询参数和表单字段都是不可信输入。限制大小与类型，在隔离目录解析，不把用户文件名直接拼接成磁盘路径或 shell 命令。第三方组件也会扩大前端供应链范围。

本地密钥可放 .streamlit/secrets.toml，但必须加入忽略规则；云端使用平台密钥设置。不要用 st.write、异常栈或缓存键输出秘密。

6. 对外部署需要补 Web 服务边界

本地开发先绑定 127.0.0.1。对外提供时增加身份验证、TLS、反向代理、请求和上传限制、依赖锁定、进程隔离、超时和日志脱敏。模型推理或长任务应移入队列，避免一个会话占住整个进程。

Streamlit Community Cloud 当前由官方描述为免费服务，可连接 GitHub 仓库部署。它的资源、休眠、隐私和可用性规则与自托管不同；企业 Snowflake 路径另行评估。

7. 与 Gradio 怎么选

相比 Gradio，Streamlit 更偏完整的数据应用，提供表格、布局、导航、Session State、缓存和多页结构。Gradio 以 Python 函数或模型为中心，Interface 与 Blocks 更适合快速做输入输出演示，并可生成可调用 API。数据仪表盘和分析工作流先看 Streamlit；包装单个模型或函数演示时，Gradio 通常步骤更少。

8. 当前验证边界

验证边界：未验证浏览器会话、重跑、缓存一致性、上传内存、认证、性能和 Cloud 限额。示例需要读者在隔离环境执行。

常见问题