Ubuntu22.04下PYTHONPATH仅交互式终端生效问题排查

该问题是Ubuntu 22.04下Python模块搜索规则、Shell环境加载逻辑不一致导致的典型环境问题，按出现概率从高到低排序，诱因如下：

• 解释器版本/环境不匹配
  交互式终端调用的Python解释器，和运行脚本时调用的解释器不是同一个二进制文件，二者的模块搜索路径完全独立。
  高频触发场景：

  1. 交互终端里已经激活了venv/conda虚拟环境，但运行脚本时直接调用了系统全局的/usr/bin/python3，或是脚本头部的shebang行硬编码指向了其他版本的Python
  2. 系统并存多个Python版本（比如默认3.10和手动安装的3.11/3.12），交互时进入的是高版本Python环境，跑脚本时默认调用的是系统自带的低版本
     验证方法：
     先在交互式Python终端执行以下代码，再把相同代码加到报错脚本的最开头运行，对比两边输出：

  import sys, os
  print("当前解释器路径:", sys.executable)
  print("读取到的PYTHONPATH:", os.environ.get("PYTHONPATH"))
  print("全量模块搜索路径:", sys.path)
  

  如果两边解释器路径不一致，直接用对应解释器的绝对路径调用脚本即可，比如虚拟环境下用/home/xxx/venv/bin/python3 your_script.py，不要直接敲无路径的python3命令。

• PYTHONPATH仅对交互式Shell生效
  如果你把export PYTHONPATH=你的模块路径的配置写在了~/.bashrc、~/.zshrc这类仅交互式Shell启动时才会加载的配置文件里，那么直接双击运行脚本、通过cron定时任务跑脚本、从其他程序调用脚本时，启动的是非交互式Shell，不会加载上述配置，自然读不到PYTHONPATH的值。
  另外如果跑脚本时加了sudo，Ubuntu默认的sudo安全策略会重置环境变量，自动剔除自定义的PYTHONPATH，哪怕当前Shell里能读到这个变量，sudo启动的进程里也拿不到对应值。
  验证方法：
  终端执行bash -c 'echo $PYTHONPATH'模拟非交互式Shell环境，如果输出为空即可确认是该问题。修复方式是把PYTHONPATH的配置写到/etc/environment（全局生效）或~/.profile（当前用户登录生效）；sudo场景可加-E参数保留当前环境变量，或修改sudoers配置的env_keep项保留PYTHONPATH。

• 本地同名模块覆盖
  Python运行脚本时，会把脚本所在的目录放在模块搜索路径的最高优先级，如果你脚本存放的目录下刚好有和待导入模块同名的.py文件、同名文件夹，Python会优先加载这个本地重名文件，不会去PYTHONPATH下查找目标模块，就会抛出找不到模块的报错。
  而交互式终端启动Python时，当前工作目录一般是用户家目录或其他非脚本目录，不存在这个重名文件，所以导入逻辑正常。
  验证方法：
  把报错脚本临时移动到空目录下运行，如果不再报错，就是存在同名冲突，删除或重命名本地的重名文件即可解决。

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