Python文件导入异常：文件存在却提示ModuleNotFoundError的原因排查

嘿，这种之前好好的突然就报错的情况确实挺让人头疼的，我来帮你梳理几个最可能的原因，你可以挨个排查：

• Python解释器环境切换了
  很多时候是不小心切到了别的环境——比如之前用项目的虚拟环境，现在误启动了全局Python或者另一个虚拟环境。不同环境的模块搜索路径完全不一样。
  你可以在终端执行which python（Linux/macOS）或者where python（Windows），看看当前用的解释器路径是不是你预期的那个。也可以在代码开头加几行输出确认：

  import sys
  print("当前Python解释器路径:", sys.executable)
  print("模块搜索路径列表:", sys.path)
  

  重点看sys.path里有没有包含你要导入的文件所在的目录。

• 模块搜索路径配置失效了
  之前你可能通过PYTHONPATH环境变量，或者代码里的sys.path.append()把目标目录加入了搜索路径，但现在这个配置没了——比如换了终端窗口没继承环境变量，或者代码里的路径拼接因为文件移动失效了。
  可以手动打印PYTHONPATH的值（终端里跑echo $PYTHONPATH），看看是不是包含目标目录。

• 文件名/目录名和内置模块/第三方包重名
  比如你的文件叫math.py，但Python有内置的math模块，这时候Python会优先加载内置模块，完全忽略你的本地文件。或者父目录名和某个第三方包重名，也会打乱导入逻辑。赶紧检查下你的文件名和所在目录名有没有和常用库撞车的。

• 文件权限或大小写问题

  • Linux/macOS下，如果当前用户没有读取文件的权限，即使文件存在也会导入失败，用ls -l看看权限位有没有r；
  • 另外，Linux/macOS区分文件名大小写，Windows不区分——比如你代码里写import Config，但实际文件是config.py，在Linux下就会直接报错。

• 文件被误移动或缓存损坏
  有时候你以为文件还在原位，其实不小心移到子目录了；或者Python生成的.pyc缓存文件损坏，也会导致导入异常。可以先删除目标目录下的__pycache__文件夹，再重新运行代码试试。

排查的时候建议从「确认Python环境」开始，这个是最常见的问题，通常很快就能找到根源。

内容的提问来源于stack exchange，提问作者Selçuk