ModuleNotFoundError 在 Linux 部署时主因是 Python 未将自定义模块路径加入 sys.path，而非缺包；根本原因是 Linux 命令行下不自动添加项目根目录，需用 os.path.dirname(os.path.abspath(__file__)) 精准添加路径，且必须置于所有 import 之前。
ModuleNotFoundError 出现在 Linux 部署时，大概率不是缺包，而是 Python 根本没找到你的自定义模块所在路径。Windows 开发环境和 Linux 运行环境的当前工作目录、__file__ 解析逻辑、以及 sys.path 初始内容都不一样，直接拷贝代码过去跑，90% 会栽在这儿。
为什么 import mypackage 在 Linux 上突然报错？
根本原因不是“没装”，而是 Python 启动时默认只搜 site-packages 和当前工作目录（os.getcwd()），而你项目里的 mypackage 很可能在上级目录或兄弟目录里。
PyCharm 或 VS Code 在 Windows 本地运行时，编辑器会自动把项目根目录加进 sys.path，但 Linux 命令行下不会——它只认你执行 python script.py 时所在的那个目录。
sys.path.insert(0, ...) 放哪儿才有效？
必须放在任何 import 语句之前，且最好紧贴文件开头。常见错误是写在函数里、写在 if __name__ == '__main__': 下面，或者用错了路径计算方式。
- 用
os.path.dirname(os.path.abspath(__file__))获取当前文件所在目录（不是工作目录） - 想导入同级目录的
utils，就加os.path.dirname(os.path.abspath(__file__)) - 想导入上一级的
src，就加os.path.dirname(os.path.dirname(os.path.abspath(__file__))) - 别用
os.getcwd()—— 它依赖你从哪启动脚本，不可靠
用 setup.py 安装比改 sys.path 更稳吗？
是，但前提是真装对了。很多人跑 pip install -e . 后还是报错，问题出在：setup.py 里 find_packages() 没覆盖到你要的目录，或者没加 __init__.py。
- 确保每个要被 import 的目录下都有
__init__.py（哪怕空文件） -
setup.py中的packages=find_packages()默认只找含__init__.py的子目录 - 如果模块在
src/下，得写成find_packages(where='src')并配package_dir={'': 'src'} - 安装后检查
pip show your-project-name输出的Location:是否指向你期望的路径
部署时要不要设 PYTHONPATH？
能不用就不用。它属于全局污染，容易和虚拟环境冲突，而且一旦忘了导出，CI/CD 或 systemd 服务就挂。真正需要它的情况极少，比如调试阶段临时绕过路径问题，或某些嵌入式场景下无法修改源码。
立即学习“Python免费学习笔记（深入）”；
- 如果非要用，写进启动脚本里：
export PYTHONPATH="/path/to/your/project:$PYTHONPATH" - 别写进
~/.bashrc—— 会影响所有 Python 进程，包括系统工具 - systemd 服务中要用
Environment=PYTHONPATH=/xxx单独指定
sys.path，有些在函数调用时才动态 import，有些甚至缓存了路径结果。所以改完路径后，务必重启整个 Python 进程，而不是 reload 模块。 
