单台Python 3.9.1设备本地运行报ModuleNotFoundError找不到my_project的原因与修复

• Python直接执行单文件脚本时，会自动把脚本所在的文件夹路径插入到sys.path搜索列表的最前端。你直接运行my_project/main.py时，解释器的搜索路径里只会包含.../my_project/这个目录，不会自动包含它的父目录（也就是存放my_project包的项目根目录）。此时执行from my_project.options import some_function的导入逻辑，需要从顶层找名为my_project的包，但搜索路径里根本没有它的父级目录，自然会抛出找不到模块的错误。
• 这套代码之前能正常运行，其他设备也没有报错，说明正常运行的环境已经把项目根目录配置进了Python的模块搜索范围（一般是通过PYTHONPATH环境变量、或者虚拟环境的自动路径配置实现的）。这次仅在Python 3.9.1的设备上触发故障，大概率是这台设备的原有路径配置失效：比如终端配置文件未加载、虚拟环境切换、系统更新重置了环境变量，导致原有路径配置丢失。
• 通过pip安装后能正常运行，是因为pip安装流程会把包信息注册到Python的全局site-packages目录下，解释器可以直接从注册路径找到包，和直接运行源码时的临时路径加载逻辑没有关联，因此不受影响。

• 调整运行方式：在项目根目录（my_project文件夹的上一级路径）下执行模块启动命令python -m my_project.main，这种运行方式会自动把当前工作目录加入搜索路径，解释器可以正常识别my_project顶层包。
• 代码内临时修正搜索路径：如果必须直接执行my_project/main.py文件，可以在main.py的所有内部包导入语句之前，手动把项目根目录加入搜索路径，示例代码：

  import sys
  from pathlib import Path
  # 获取项目根目录（当前main.py所在文件夹的上一级目录）
  project_root = Path(__file__).resolve().parent.parent
  sys.path.insert(0, str(project_root))
  

• 恢复环境配置：检查这台设备上的PYTHONPATH环境变量配置，把项目根目录的绝对路径重新加入配置即可，无需修改代码，和之前正常运行时的环境逻辑保持一致。

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