Streamlit稳定运行需确保Python版本为3.8–3.10（推荐3.9）、使用虚拟环境隔离依赖，并避免直接用streamlit run开发模式对外服务，应加参数配置端口、地址及安全选项，长期运行建议配合nohup与nginx。
直接用 python -m venv + pip install streamlit 就能跑起来，但想稳定展示、不踩坑，关键在 Python 版本、依赖隔离和启动方式三处。
Python 版本必须卡在 3.8–3.10 范围内
Streamlit 在 3.11+ 上存在部分依赖兼容问题，比如 plotly 或 pydeck 可能加载失败，报错类似 ModuleNotFoundError: No module named 'typing_extensions'。实测 3.9 是目前最稳的平衡点——既支持所有主流可视化库，又避开 3.10 后某些 asyncio 行为变更带来的 session 重置异常。
- 检查当前版本：
python --version（Windows）或python3 --version（macOS/Linux） - 若版本不符，优先用
pyenv切换，或直接下载 Python 3.9 官方安装包（勾选 “Add Python to PATH”） - 别用系统自带 Python（如 macOS 的 /usr/bin/python3），它常被锁死且无法升级 pip
必须用虚拟环境隔离依赖
不建虚拟环境直接 pip install streamlit，后续加个 pandas 或 plotly 就可能触发版本冲突，典型现象是 st.plotly_chart 渲染空白、控制台无报错，只在浏览器 DevTools 的 Network 标签里看到 404 for plotly.min.js。
- 创建环境：
python -m venv streamlit_env - 激活环境：Windows 执行
streamlit_env\Scripts\activate，macOS/Linux 执行source streamlit_env/bin/activate - 装核心包：
pip install streamlit pandas plotly numpy（matplotlib可选，plotly交互性更强） - 验证：
streamlit hello能正常打开页面，且右上角显示 “Running on http://localhost:8501”
启动命令别用默认开发模式直连公网
streamlit run app.py 是开发利器，但它的热重载、源码可读、无鉴权、单线程特性，让它完全不适合对外展示。常见问题包括：别人刷新页面后状态丢失、并发稍高就卡死、URL 里暴露 .py 路径、甚至被爬虫反复请求拖垮进程。
立即学习“Python免费学习笔记（深入）”；
- 本地演示没问题，但只要需多人访问，就得加参数：
streamlit run app.py --server.port=8502 --server.address=127.0.0.1 - 真正上线前必须禁用开发模式：
--server.enableCORS=false --server.enableXsrfProtection=true - 别信“改
streamlit.config.toml就能生产化”——配置文件只调端口和日志，不解决并发和安全本质问题 - 需要长期运行？用
nohup streamlit run app.py --server.port=8502 > streamlit.log 2>&1 &，再配个 nginx 反向代理（非必须但强烈建议）
最容易被忽略的是：所有 st.cache_data 或 st.cache_resource 的函数，如果内部用了全局变量或文件路径硬编码，重启服务后缓存会失效，导致首次加载极慢——把数据加载逻辑单独封装、加 @st.cache_data(ttl=3600) 并显式传参，比靠脚本重跑更可控。
