必须锁定Python小版本（如python:3.11.7-slim-bookworm）并按COPY requirements.txt→RUN pip install→COPY . .顺序编写Dockerfile，否则因镜像自动升级或缓存失效导致构建失败、运行异常或启动变慢。
直接说结论：别用 python:latest 或 python:slim 不带小版本号的镜像，否则构建可能突然失败；Dockerfile 必须先 COPY requirements.txt 再 RUN pip install，否则缓存失效、构建变慢。
为什么基础镜像必须锁定 Python 小版本（如 python:3.11.7-slim-bookworm）
Python 官方镜像的 python:3.11-slim 标签会随时间指向不同微版本（比如某天从 3.11.6 变成 3.11.9），而你的依赖（如 pydantic、numpy）可能只兼容特定微版本。上线前测试通过，上线时因镜像自动升级导致 ImportError 或 segfault，排查成本极高。
常见错误现象：
- 本地
docker build成功，CI/CD 流水线却报ModuleNotFoundError: No module named 'xxx' - 容器启动后立即退出，
docker logs显示Illegal instruction (core dumped)（常见于 numpy + 新版 Python ABI 不匹配）
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 查清你项目实际运行的 Python 版本：
python --version，然后去 Docker Hub python 镜像页 找对应小版本的 slim 标签，例如python:3.11.7-slim-bookworm - 避免用
python:3.11（含完整 apt 工具链，镜像大、攻击面广）或python:3.11-alpine（musl libc 兼容性差，某些 C 扩展如psycopg2容易出错）
COPY requirements.txt 和 COPY . . 的顺序为什么不能颠倒
Docker 构建是分层的，每一层都可被缓存。如果先 COPY . . 再 RUN pip install，只要代码任意一行改动，整个 pip install 层就失效——每次都要重装所有依赖，构建时间从秒级拉长到分钟级。
使用场景：
- 日常开发中频繁改
app.py，但requirements.txt很少动 - CI/CD 中希望复用上一次构建的依赖层，加速流水线
正确顺序（关键四步）：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
COPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY . .-
WORKDIR /app（必须显式设置，否则gunicorn app:app会找不到模块）
容易踩的坑：
- 漏掉
WORKDIR /app，导致 CMD 中路径解析失败 - 把
requirements.txt放在子目录（如./src/requirements.txt），但COPY路径写错，结果 pip 安装时找不到文件，报ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'
EXPOSE 和 ports 双配置缺一不可
EXPOSE 8000 在 Dockerfile 里只是文档说明，不触发任何端口映射；真正让宿主机能访问容器服务，必须在运行时通过 -p 8000:8000 或 docker-compose.yml 的 ports 字段显式声明。
性能与兼容性影响：
- 不写
EXPOSE不影响功能，但会让其他开发者/运维不清楚服务监听端口，增加协作成本 -
ports写成"8000"（单端口）而非"8000:8000"（host:container），Docker 会随机分配宿主机端口，导致无法稳定访问
实操建议：
立即学习“Python免费学习笔记（深入）”；
- Dockerfile 中
EXPOSE值必须和应用代码中绑定的地址一致（如 Flask 的app.run(host='0.0.0.0', port=8000)） - 运行命令必须带
-p：docker run -p 8000:8000 my-python-app - 若用
docker-compose.yml，确保ports下写全格式：- "8000:8000"，且不要遗漏environment:或env_file:注入运行时配置
启动命令必须用 exec 形式保证 PID 1 是主进程
如果写成 CMD python app.py（shell 形式），实际启动的是 shell 进程（PID 1），而 python app.py 变成它的子进程。此时容器收不到 SIGTERM，无法优雅关闭，docker stop 会超时后强制 kill，导致数据库连接未释放、临时文件未清理。
正确写法（exec 形式）：
CMD ["python", "app.py"] # 或 gunicorn 场景： CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "app:app"]
容易忽略的点：
- Web 框架默认绑定
127.0.0.1，必须改成0.0.0.0，否则容器内其他进程（如健康检查）也访问不了 - 没加
--bind 0.0.0.0:8000导致容器日志显示Running on http://127.0.0.1:8000，但宿主机curl localhost:8000超时 - 忘记在
requirements.txt中固定所有依赖版本（用pip freeze > requirements.txt或pip-compile），导致不同时间构建的镜像行为不一致
