ModuleNotFoundError 根本原因在于模块结构不合法或执行方式错误，而非单纯路径未添加；Python 导入机制只识别符合包规范（含 __init__.py）的目录，且依赖当前工作目录和启动方式（如 python -m），sys.path 手动修改仅作临时调试。
ModuleNotFoundError 的根本原因不是路径没加对
绝大多数人遇到 ModuleNotFoundError 第一反应是“往 sys.path 里 append 个路径”，但实际问题往往出在模块结构或执行方式上。Python 导入机制只认「包结构」和「当前工作目录/启动路径」，不认你手动塞进 sys.path 的任意文件夹——除非那个路径下有合法的 __init__.py（或满足 PEP 420 的 namespace package）。
- 直接运行
python my_script.py：当前工作目录自动加入sys.path[0]，但子目录不会自动变成包 - 用
python -m mypackage.mymodule启动：要求mypackage是一个可发现的顶层包（即其父目录在sys.path中） -
sys.path.append('/path/to/dir')之后仍报错？大概率是该目录下没有__init__.py，或名字拼错了（比如写成__init.py少了个点）
检查 sys.path 时重点看前三项
sys.path 列表很长，但真正影响导入的通常是前三个位置：''（空字符串，代表当前工作目录）、Python 安装的 site-packages、以及用户级 site-packages。后面几十项基本是冗余路径，不用逐个排查。
-
print(sys.path[0])—— 确认你运行脚本时所在的目录是不是你期望的“包根目录” -
print(os.getcwd())—— 和sys.path[0]对比，二者不一致说明你在别的目录下执行了python /full/path/to/script.py - 如果
sys.path[0]是空字符串，但你想导入的是同级目录下的utils/，必须确保utils/__init__.py存在，且用import utils（不是import utils.something再报错才回头补）
临时修改 sys.path 的正确姿势
硬编码 sys.path.append() 是反模式，仅限调试；生产环境应通过安装或正确组织项目结构解决。但如果真要临时加，必须注意顺序和路径有效性：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用
os.path.abspath()构造路径，避免相对路径在不同工作目录下失效：sys.path.insert(0, os.path.abspath('./lib')) - 插到
sys.path[0]前面（insert(0, ...)），否则可能被已有的同名包覆盖 - 加完立刻验证：
importlib.util.find_spec('mypkg')返回None就说明路径无效，别等 import 时报错才排查 - 不要在
__init__.py里改sys.path—— 模块加载顺序不确定，容易引发循环依赖或静默失败
比 sys.path 更常被忽略的是 PYTHONPATH 和 .pth 文件
sys.path 不是唯一来源。环境变量 PYTHONPATH 会 prepend 到 sys.path 开头，而 site-packages 下的 .pth 文件也能动态注入路径——这两处出问题时，print(sys.path) 看起来正常，但导入行为异常。
立即学习“Python免费学习笔记（深入）”；
- 检查是否误设了
PYTHONPATH：echo $PYTHONPATH（Linux/macOS）或echo %PYTHONPATH%（Windows） - 查看
site-packages目录下有没有可疑的.pth文件：python -c "import site; print(site.getsitepackages())" - 某些 IDE（如 PyCharm）会悄悄把项目根目录加进
PYTHONPATH，导致代码在终端跑不通——这不是 bug，是环境不一致
sys.path；路径本身只是表象，背后是 Python 对「什么是包」「从哪找包」的严格定义。 
