速查·Dockerfile 编写最佳实践清单

速查·Dockerfile 编写最佳实践清单

把 Dockerfile 写好，能让镜像更小、构建更快、缓存命中率更高。本条是日常编写 Dockerfile 时的速查清单。

分层与缓存

• 把不常变的层放前面：基础镜像、系统包、Python 依赖这些变化少的指令放前面，代码放最后。这样改代码时前面的层能命中缓存，不用重新构建。
• 合并 RUN 指令：多个 RUN apt-get install 合并成一条（用 && 连接），减少层数。每条 RUN 是一层，层越多镜像越大。
• 清理安装残留：apt-get install 后加 rm -rf /var/lib/apt/lists/*，pip install 加 --no-cache-dir，别把包管理器的缓存打进镜像。

依赖管理

• requirements.txt 锁版本：用 package==1.2.3 精确锁版本，而不是 package>=1.2.0，保证跨机器构建一致。
• 分开安装系统依赖和 Python 依赖：系统依赖用 apt，Python 依赖用 pip，别混在一个 RUN 里（出错难排查）。

.dockerignore 必备

不写 .dockerignore 会把 .git、node_modules、__pycache__、数据集、模型权重全部打进镜像，体积爆炸且可能泄露敏感信息。最少要忽略：.git、*.pyc、__pycache__、.venv、data/、*.bin、*.safetensors。

CUDA 相关

• 选官方 CUDA 基础镜像：nvidia/cuda:12.x.x-cudnn8-runtime-ubuntu22.04 这种，别自己装 CUDA。
• runtime 还是 devel：生产用 runtime（小），调试用 devel（带编译工具）。
• PyTorch 版本要和镜像 CUDA 匹配：PyTorch 官方有对应 CUDA 版本的 wheel，装错会报各种 CUDA 错误。

详细原理见正文第二章 2.1「镜像分层设计」。