本文详解如何在 PyCharm 中配置 Python 路径与导入方式，解决 streamlit run main.py 报 ModuleNotFoundError: No module named 'demo' 及 st.session_state.messages 未初始化等典型问题。
本文详解如何在 pycharm 中配置 python 路径与导入方式，解决 `streamlit run main.py` 报 `modulenotfounderror: no module named 'demo'` 及 `st.session_state.messages` 未初始化等典型问题。
在 PyCharm 中运行依赖本地包（如 demo）的 Streamlit 应用时，常见两类错误：
- ModuleNotFoundError: No module named 'demo'：源于 Python 解释器无法定位项目根目录下的包，导致绝对导入失败；
- AttributeError: st.session_state has no attribute "messages"：因 Streamlit 每次页面刷新会重置 session state，未做初始化即访问属性所致。
✅ 正确配置项目结构与 Python Path
确保项目结构清晰且符合 Python 包规范：
project_root/ ├── demo/ │ ├── __init__.py # 必须存在（可为空），标识为包 │ ├── example.py │ └── ... ├── gui/ │ ├── main.py # Streamlit 入口文件 │ └── ... └── __init__.py # 可选，但推荐在 project_root 添加以支持顶层导入
关键操作（PyCharm 设置）：
- 打开 File → Settings → Project:
→ Python Interpreter； - 点击右上角齿轮图标 → Show All… → 选择对应解释器 → 点击右侧 Show interpreter paths；
- 点击 + 号，添加项目根目录路径（即 project_root 的绝对路径）；
- 确保该路径位于 interpreter paths 列表顶部（优先级最高），使 import demo 可被解析。
? 替代方案：在 gui/main.py 开头动态追加路径（仅作临时调试，不推荐生产使用）：
import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent)) # 将 project_root 加入路径 from demo.example import your_function
✅ 正确初始化 Streamlit Session State
Streamlit 的 st.session_state 是会话级状态容器，不会自动持久化或初始化。首次访问 st.session_state.messages 前必须显式初始化：
import streamlit as st
# ✅ 正确初始化（放在 main.py 最上方逻辑处）
if "messages" not in st.session_state:
st.session_state.messages = []
# 后续即可安全使用
for msg in st.session_state.messages:
with st.chat_message(msg["role"]):
st.markdown(msg["content"])
若使用 st.session_state.xxx 未判空直接读写，必触发 AttributeError。
✅ 推荐运行方式：统一使用 streamlit run + 正确路径
- ❌ 不要直接点击 PyCharm 的 ▶️ Run 按钮（它按普通 Python 脚本执行，绕过 Streamlit 运行时机制）；
- ✅ 始终使用终端命令运行（确保环境一致）：
cd /path/to/project_root streamlit run gui/main.py
此时只要 project_root 已加入 Python path（通过上述 PyCharm 配置或 PYTHONPATH 环境变量），from demo.example import ... 即可正常解析。
⚠️ 注意事项总结
- __init__.py 文件缺一不可，否则 demo 不被视为合法包；
- 相对导入（如 from ..demo.example import xxx）在 Streamlit 中不可靠，因其执行上下文非标准模块导入链，强烈建议使用绝对导入 + 正确 sys.path 配置；
- PyCharm 的 Run Configuration 若需调试，应设置 Script path 为 gui/main.py，并在 Environment variables 中添加 PYTHONPATH=/path/to/project_root；
- Streamlit 官方推荐将入口文件置于项目根目录（如 app.py），避免深层嵌套带来的路径复杂性。
完成以上配置后，streamlit run gui/main.py 将顺利导入本地包，且 session state 初始化稳定，兼顾开发效率与运行健壮性。
