根本原因是Python解释器未在sys.path中找到模块，或模块未被识别为合法包；需确认pip与python指向同一环境、检查__init__.py存在性、使用python -m pip安装、校准PYTHONPATH及工作目录。
根本原因不是代码写错了，而是运行时 Python 解释器压根没“看见”你要导入的模块——它不在 sys.path 里，或者根本没被识别为合法包。
确认当前解释器和 pip 是否指向同一环境
这是 90% 部署报错的起点。你用 pip install requests 装的包，可能装在系统 Python 里，但部署脚本实际跑在虚拟环境或容器里的另一个 Python 进程中。
- 在部署机器上直接运行：
which python和which pip，看路径是否一致 - 检查脚本开头是否显式指定了 Python 解释器（比如
#!/usr/bin/env python3），该解释器对应的pip才是有效的 - 最稳妥安装方式：
python -m pip install requests—— 强制给当前python安装，不依赖pip命令绑定
检查自定义模块是否被当作包识别
部署目录结构常被简化或打包，__init__.py 文件容易被忽略或误删，导致整个目录不被视为包。
- 只要用了
from mypkg import utils这类带点号的导入，mypkg/目录下就必须有__init__.py（哪怕为空） - 如果用
zipapp或pyinstaller打包，确认构建命令是否包含子目录及其__init__.py - 避免用
python script.py直接运行深层脚本（如src/main.py），这会让src/成为顶层，from app import config就会失败
PYTHONPATH 和工作目录在部署中极易失效
本地开发时靠 IDE 自动设工作目录，但部署时往往用 systemd、supervisor 或 Docker 启动，工作目录默认是根目录或服务配置指定路径，sys.path[0] 就不是你预期的位置。
- 不要依赖
sys.path.append('./lib')——.是当前工作目录，部署时不可控 - 改用绝对路径：
sys.path.append(os.path.dirname(os.path.abspath(__file__)) + '/../lib') - Docker 中推荐通过
ENV PYTHONPATH /app/src显式设置，比代码里硬编码更可靠 - 若用
python -m mypackage.cli方式启动，确保mypackage/在PYTHONPATH或当前目录下，且不含拼写错误
第三方库名和导入名不一致导致的静默失败
有些包安装名和导入名不同（比如 pip install python-dotenv，但代码里是 import dotenv），部署时只按错误名重试安装，永远装不对。
- 查官方文档确认导入名，而不是包名；常见陷阱：
pip install Pillow→from PIL import Image，不是import pillow - 用
pip show python-dotenv看输出里的Name:和Summary:字段，验证是否真装对了 - 在部署脚本里加一行诊断：
python -c "import requests; print(requests.__version__)"，验证模块可导入且版本符合预期
真正麻烦的不是找不到包，而是你认为它“应该在那儿”，而 Python 解释器连它的文件路径都没扫描过——每次部署前，先跑一遍 python -c "import sys; print(sys.path)"，比反复 pip install 更快定位问题。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
