ModuleNotFoundError 根本原因是 Python 未在 sys.path 中找到目标模块路径，需检查工作目录、sys.path、__init__.py 存在性、命名规范及运行方式差异，并优先用绝对路径而非相对路径。
ModuleNotFoundError 本质是 Python 找不到你要导入的模块路径，不是代码写错了，而是解释器根本没“看见”那个文件。
确认模块文件是否在 Python 的 sys.path 中
Python 只会在 sys.path 列出的目录里搜索模块。运行以下代码查看当前有效路径：
import sys
print('\n'.join(sys.path))
常见问题：你的模块文件（比如 my_utils.py）放在项目根目录，但当前工作目录不是那里；或者你用 IDE 运行脚本时，工作目录被设成了其他位置。
- 临时加路径：在导入前插入
sys.path.append('/absolute/path/to/your/module/dir') - 更稳妥的做法：把模块所在目录加入环境变量
PYTHONPATH（Linux/macOS 加到~/.bashrc或~/.zshrc；Windows 在系统属性 → 环境变量里设置） - 注意：相对路径如
sys.path.append('./lib')容易因工作目录变化失效，优先用os.path.dirname(__file__)构造绝对路径
检查模块命名与 import 语句是否匹配
Python 对大小写、下划线、点号非常敏感，且不支持带连字符的文件名。
立即学习“Python免费学习笔记（深入）”；
- 文件名是
data_loader.py，就只能用import data_loader或from data_loader import xxx，不能写成import data-loader（语法错误）或import DataLoader（找不到） - 如果模块在子目录中，比如
src/utils/helpers.py，且该目录下有__init__.py，才可以用from src.utils import helpers - 没有
__init__.py的目录，Python 默认不认为它是包，from utils import helpers会失败（除非该目录已在sys.path中）
区分运行方式导致的路径差异
直接运行 python script.py 和用 python -m package.module 对模块解析逻辑完全不同。
- 用
python my_script.py：当前目录（即my_script.py所在目录）自动加入sys.path[0]；同级的my_module.py可直接import my_module - 用
python -m my_package.main：要求my_package是一个包含__init__.py的目录，且该目录必须在sys.path中（通常需 cd 进父目录再执行） - VS Code / PyCharm 默认以文件所在目录为工作目录，但如果你改过 “Run in Terminal” 的启动路径，
sys.path[0]就可能不对
验证模块能否被正确识别为包
即使文件存在，Python 也可能拒绝把它当作可导入模块——尤其是顶层目录缺少 __init__.py 或结构不满足包规范时。
- 单个 .py 文件想被导入，只需确保它所在目录在
sys.path中，无需__init__.py - 若要使用点号导入（如
from mypkg.sub import func），则mypkg/和mypkg/sub/都必须存在空的__init__.py文件（哪怕内容为空） - 运行
python -c "import mymodule; print(mymodule.__file__)"可快速验证是否真能加载，并看到它实际来自哪个路径 - 注意：.pyc 缓存有时会干扰判断，可删掉 __pycache__ 目录再试
最常被忽略的是工作目录和 sys.path[0] 的隐式绑定关系——很多人以为“文件就在旁边”，其实 Python 根本没从那个位置开始找。动手前先打印 sys.path 和 os.getcwd()，比反复改 import 语句高效得多。
