Python 导入错误 — ModuleNotFoundError 与循环导入

核对 sys.executable 与 sys.path，排查同名文件遮蔽、虚拟环境错位和循环导入，修复 Python 模块无法导入的问题。

现象

报 ModuleNotFoundError: No module named 'requests'，或出现 ImportError: cannot import name 'UserService' from partially initialized module；同一包在终端可用，脚本、cron 或容器中却失败；堆栈指向与模块同名的本地文件。

诊断

先确认当前解释器与搜索路径：

python -c "import sys; print(sys.executable); print(*sys.path, sep='\n')"
python -c "import importlib.util; print(importlib.util.find_spec('requests'))"
python -m pip show requests
python -X importtime -c "import app" 2>&1 | tail -25

find_spec 返回 None 表示该解释器确实找不到模块；返回项目内路径则说明本地 requests.py 遮蔽了真正的包。pip show 的安装位置若不在 sys.path 中，说明包装进了另一个环境。循环导入时 -X importtime 会显示 A 尚未执行完就被 B 引用，最终出现 partially initialized module。

修复

激活项目虚拟环境，并用 python -m pip 安装，确保包装进正在运行的解释器：

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m app.main

删除或重命名遮蔽标准库、第三方库的本地文件；循环依赖可把共享类型抽到独立模块，或在函数内部延迟导入，类型注解使用 TYPE_CHECKING。以 python -m package.module 方式运行，让包相对导入正确解析。

验证

在干净 shell 中用同一解释器重新运行失败入口，导入应成功；执行完整测试集不再出现导入告警。最后在最初失败的容器或 cron 环境中复跑，确认不是只在 IDE 中生效。不要把大量路径硬塞进 PYTHONPATH，那会掩盖错误的包结构。