Streamlit Cloud主文件移至嵌套目录后出现ModuleNotFoundError问题排查

问题根源 #

Streamlit Cloud默认以项目根目录作为工作目录，当主文件streamlit_app.py移到src/alpha/后，Python的模块搜索路径（sys.path）默认不包含src目录，导致无法识别你要导入的模块。而本地通过Poetry运行时，Poetry会自动将src目录加入模块搜索路径，因此不会出现报错。

具体解决步骤 #

1. 确认pyproject.toml的包配置 #

确保pyproject.toml中正确声明了源码目录，让Streamlit Cloud能识别你的模块：

[tool.poetry]
# 保留原有配置...
packages = [
    { include = "src" },
]

如果仅需包含alpha子目录，也可以写成：

packages = [
    { include = "src/alpha" },
]

2. 在streamlit_app.py中手动添加模块搜索路径 #

在src/alpha/streamlit_app.py的最开头加入以下代码，强制将src目录加入Python的模块搜索路径：

import sys
from pathlib import Path

# 计算项目根目录（当前文件位于src/alpha/，向上两级即为根目录）
root_dir = Path(__file__).resolve().parent.parent.parent
# 将src目录添加到sys.path
sys.path.append(str(root_dir / "src"))

这段代码能确保无论运行环境的工作目录是什么，Python都能找到src下的所有模块。

3. 调整导入语句 #

根据src目录的结构调整导入路径，比如：

• 若src下有utils模块：from utils import some_function
• 若utils在alpha目录下：from alpha.utils import some_function

4. 确认Streamlit Cloud的主文件路径 #

在Streamlit Cloud的项目设置中，检查Main file path是否设置为src/alpha/streamlit_app.py，确保平台能正确定位你的主应用文件。

验证方法 #

部署后可以在应用日志中添加以下代码，查看当前sys.path确认src目录是否已被加入：

import sys
print("当前sys.path:", sys.path)

内容的提问来源于stack exchange，提问作者xkeshav