ModuleNotFoundError 总在 import 时报错，因为 Python 导入是惰性的：import 语句执行时才解析路径、查找文件、加载模块；错误本质是当前 sys.path 中无匹配包或文件，而非运行时其他阶段。
为什么 ModuleNotFoundError 总在 import 时才报，而不是运行时其他地方？
因为 Python 的模块导入是惰性的——import 语句执行时才去解析路径、查找文件、加载代码。错误不是“找不到模块”，而是“在当前 sys.path 列表里没匹配到对应包名或文件”。常见现象包括：本地能跑，换环境就崩；IDE 里不报错，终端运行就炸；改了目录结构后突然 ModuleNotFoundError: No module named 'xxx'。
排查核心就一条：搞清 Python 此刻到底在哪些路径里找模块。别猜，直接看：
- 运行
python -c "import sys; print('\n'.join(sys.path))"，确认当前解释器的搜索路径 - 检查你要 import 的模块是否落在其中某个路径下（比如
./src或~/venv/lib/python3.x/site-packages） - 特别注意第一个路径（通常是当前工作目录），它优先级最高——但很多人 cd 错了目录，导致相对导入失效
相对导入（from . import xxx）失败的三个硬性条件
相对导入不是语法糖，它依赖运行上下文。哪怕写法完全正确，只要不满足以下任一条件，就会变成 ModuleNotFoundError 或更隐蔽的 ImportError: attempted relative import with no known parent package：
- 模块必须作为包的一部分被导入（即不能用
python mypackage/mymodule.py直接运行） - 启动方式必须是
python -m mypackage.mymodule（注意-m），且当前目录在包的父级 -
__init__.py文件必须真实存在（哪怕是空文件），且路径层级和点号数量严格对应（from ..utils import helper表示上两级）
典型翻车场景：把一个脚本从 scripts/ 拖进 src/myapp/ 后加了 from ..config import settings，却忘了补 src/__init__.py 和改启动命令。
立即学习“Python免费学习笔记（深入）”；
虚拟环境中 pip install -e . 没生效？先查 pip list 和 site-packages
开发时习惯用 pip install -e . 把本地包“软链接”进 site-packages，但很容易忽略两个事实：这个操作只影响当前激活的虚拟环境；而且它不会自动刷新已缓存的 sys.path。如果你在安装后又开了新终端、换了 Python 解释器、或者用了 IDE 自带的 Python（而非 venv/bin/python），那 import 依然会失败。
- 运行
pip list | grep your-package-name，确认包名出现在列表中 - 检查
pip show your-package-name输出的Location:路径，是否指向你预期的源码目录 - 如果显示的是
.../site-packages/your_package-0.1.0.dist-info（而非源码路径），说明装的是 wheel，不是 editable 模式 - 重启 Python 进程（包括 Jupyter kernel、IDE 的 Python console）——旧进程不会自动 reload
sys.path
PyCharm / VS Code 显示正常但终端报错？重点核对解释器和工作目录
IDE 通常会偷偷帮你配置 PYTHONPATH、修改 sys.path、甚至把项目根目录自动加进解释器设置里。这让你在编辑器里 import 一路绿灯，一到终端就跪。最稳的验证方式是脱离 IDE，纯命令行复现：
- 用
which python和python -c "import sys; print(sys.executable)"确认终端用的是哪个解释器 - 用
pwd看当前工作目录，再对比 IDE 的 “Run Configuration” 里的 “Working directory” 设置 - 临时加一句
print([p for p in sys.path if 'your_project' in p])，看路径是不是被 IDE 注入了但终端没有 - VS Code 用户注意：
python.defaultInterpreterPath和python.terminal.executeInFileDir这两个设置会极大影响行为
真正麻烦的永远不是 import 语法，而是你根本不知道 Python 此刻信任谁的路径——多打两行 print(sys.path)，比重装十次 pip 都管用。
