ModuleNotFoundError本质是Python在sys.path中未找到目标模块，主因包括模块未安装、环境错配、路径缺失、导入名与包名不符、虚拟环境未激活或IDE解释器配置错误。
pip install 依赖版本不一致导致的 ImportError 或 ModuleNotFoundError
Python 项目在容器里报 ImportError: No module named 'xxx' 或 ModuleNotFoundError，绝大多数不是没装包，而是装了但版本不对、路径不对、或被其他同名包覆盖。
- 常见诱因是
requirements.txt没锁版本，比如只写requests而非requests==2.31.0，Docker 构建时拉到新版，而代码里用了已弃用的 API - 另一种是镜像里残留旧包：比如先
COPY . .再RUN pip install，结果项目目录下有venv/或.eggs/，被 Python 自动加入sys.path，干扰了 pip 安装的包 - 还有跨平台 C 扩展包（如
numpy、psycopg2）在alpine镜像里缺编译工具链，装完 import 失败，错误信息常含undefined symbol或ImportError: libc.musl-x86_64.so.1
建议做法：
- 构建前用
pip freeze > requirements.txt锁死所有依赖，包括间接依赖 - Dockerfile 中严格按顺序：先
COPY requirements.txt .，再RUN pip install --no-cache-dir -r requirements.txt，最后COPY . . - 避免在构建上下文中包含
venv、.git、<strong>pycache</strong>，用.dockerignore排除 - 若必须用
alpine，改用psycopg2-binary替代psycopg2，或切回python:3.11-slim-buster
os.path 和 open() 文件路径权限失败
立即学习“Python免费学习笔记（深入）”；
容器内读不到宿主机挂载的文件，报 Permission denied 或 No such file or directory，本质是路径映射 + 权限双重失效。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- Windows/macOS 上 Docker Desktop 默认只共享特定驱动器（如 C:\ 或 /Users），若数据放在 D:\ 或 /opt，需手动勾选共享设置
- Linux 宿主机挂载时若源目录属主 UID 不匹配容器内用户（默认 root），且目标路径无读权限，就会拒绝访问
- Python 用
os.listdir()或open('data/input.csv')时，路径是相对于容器内WORKDIR的，不是宿主机路径
关键检查点：
- 运行容器时用
-v /host/path:/container/path:ro显式声明只读，避免权限争议 - 在容器里执行
ls -l /container/path和id，确认 UID/GID 匹配、文件存在且可读 - Python 代码中避免硬编码绝对路径，改用
Path(<strong>file</strong>).parent / "data" / "input.csv"（需from pathlib import Path）
docker run 启动后立即退出，日志为空
CMD 执行完就退出，不是“服务没起来”，而是进程生命周期管理出错。
- 常见写法
CMD ["python", "app.py"]在脚本末尾没加input()或while True:，Python 解释器跑完就 exit，容器随之终止 - Web 服务（如 Flask、FastAPI）没监听
0.0.0.0:8000，只监听127.0.0.1:8000，外部无法访问，健康检查失败，K8s 可能直接 kill -
ENTRYPOINT和CMD组合不当，比如ENTRYPOINT ["python"]+CMD ["app.py"]是对的，但若写成ENTRYPOINT ["python app.py"]（字符串形式），shell 解析会绕过 exec 模式，信号无法透传
应确保：
- 主进程长期存活：Flask 加
app.run(host="0.0.0.0", port=8000)，不要漏host参数 - 使用
exec形式 CMD/ENTRYPOINT，避免 shell 层 wrapper - 本地测试时加
-it参数，方便观察 stdout/stderr 实时输出
复杂点在于，这些异常往往叠加出现——比如路径错导致配置加载失败，进而触发错误的依赖导入逻辑，最终表现为模块找不到。调试时别只盯着最后一行报错，得一层层验证：镜像里有没有包？包能不能 import？文件存不存在？权限够不够？进程是不是真在跑？
