Streamlit Session State 初始化错误的根源与正确使用方式

Streamlit 的 st.session_state 仅在通过 streamlit run 启动应用时才被完整初始化；若直接用 python script.py 执行，Session State 代理未激活，导致 KeyError，即使代码中已做存在性检查也无法避免。

Streamlit 的 `st.session_state` 仅在通过 `streamlit run` 启动应用时才被完整初始化；若直接用 `python script.py` 执行，Session State 代理未激活，导致 KeyError，即使代码中已做存在性检查也无法避免。

Streamlit 并非普通 Python 脚本框架——它的会话状态（st.session_state）依赖于完整的运行时环境，该环境由 streamlit run 命令启动的服务器进程提供。当你执行 python your_app.py 时，Streamlit 的核心运行时（包括 Session State 管理器、状态同步机制和前端通信通道）根本未被加载，st.session_state 实际上是一个空壳代理对象（SessionStateProxy），其内部字典为空且不可写。此时，尽管你写了：

if "show_text" not in st.session_state.keys():
    st.session_state["show_text"] = False

这段逻辑看似执行了初始化，实则失效：st.session_state.keys() 在未激活环境下返回空迭代器，条件为真，但后续赋值 st.session_state["show_text"] = False 不会真正写入任何状态——它被静默忽略或触发内部异常（取决于 Streamlit 版本），最终导致后续访问 st.session_state["show_text"] 时抛出 KeyError。

⚠️ 关键事实：

• ✅ 正确启动方式：streamlit run app.py → 触发完整 runtime，st.session_state 可读可写；
• ❌ 错误启动方式：python app.py → 仅执行顶层 Python 代码，无 Streamlit 上下文，st.session_state 不可用；
• ? 错误堆栈顶部必含警告：WARNING ... Session state does not function when running a script without 'streamlit run'——这是最权威的诊断依据。

你观察到的“第二个示例不报错”，本质是侥幸未触发读取：它只在按钮点击后执行 st.write(st.session_state["show_text"])，而此时若页面已加载（即已通过 streamlit run 启动），状态已就绪；但若用 python 直接运行，该行同样会崩溃——只是你未实际点击按钮，未走到读取分支。

✅ 正确实践建议：

1. 始终使用 streamlit run app.py 启动应用，这是唯一受支持的入口方式；
2. 初始化逻辑无需额外防护，但推荐采用更健壮的写法（虽非必需）：

import streamlit as st

# 推荐：使用 setdefault 或直接赋默认值（语义更清晰）
st.session_state.setdefault("show_text", False)
# 或
if "show_text" not in st.session_state:
    st.session_state.show_text = False  # 支持点号访问，更简洁

st.markdown("# My App")

if st.button("Show text!"):
    st.session_state.show_text = True

if st.session_state.show_text:
    st.markdown("Lorem ipsum...")

3. 开发时可通过 streamlit run --server.port=8501 app.py 指定端口，配合热重载提升效率；
4. 若需脚本化部署或 CI/CD，确保调用命令为 streamlit run，而非 python。

总结：KeyError 不是代码缺陷，而是运行模式误用。Streamlit 的设计哲学决定了其状态管理必须依托于其专用运行时——理解并尊重这一约束，是构建可靠 Streamlit 应用的第一步。