docker build 是什么
docker build 按 Dockerfile 构建镜像：把构建上下文交给构建器，逐条执行指令，可执行类指令产出文件系统层，配置类指令写入镜像元数据，最后打包成本地镜像。Docker 23 起默认使用 BuildKit 引擎，并行度与缓存能力都比老的构建器好。
基本信息
| 语法 | docker build [选项] 上下文路径 |
|---|---|
| 常用选项 | -t 打标签 -f 指定 Dockerfile --build-arg 传参 --no-cache 不读缓存 --target 指定阶段 |
| 构建引擎 | BuildKit（Docker 23+ 默认），可用 --progress=plain 看完整步骤日志 |
| 上下文 | 命令最后那个路径，通常是点号，COPY 只能引用上下文内的文件 |
典型使用场景
- 发布应用镜像：从源码构建带版本标签的镜像，再推送到镜像仓库供部署使用
- 本地验证 Dockerfile 改动：改完指令先小规模构建一次，确认能过再提交
- 调试多阶段构建的中间阶段：用 --target 只构建到指定阶段，快速检查产物
- 流水线构建：CI 里用 buildx 构建多平台镜像，配合缓存导入导出加速
- 排查构建失败：读取完整步骤日志，定位第一个非缓存步骤的报错
常用示例
常用示例
docker build -t app/web:1.0 . # 用当前目录上下文构建
docker build -f docker/Dockerfile.prod -t app/web:1.0 . # 指定 Dockerfile
docker build --no-cache -t app/web:1.0 . # 完全不用缓存重建
docker build --target build -t app/web:debug . # 只构建到某个阶段
docker build --progress=plain -t app/web:1.0 . 2>&1 | tail -50 # 看完整日志常用选项读法
| 选项 | 作用 | 注意 |
|---|---|---|
| -t | 给产物打标签 | 可重复多次，一次打多个标签 |
| -f | 指定 Dockerfile 路径 | 路径相对当前目录，不影响上下文位置 |
| --no-cache | 忽略层缓存 | 依赖更新后做全量验证构建时用 |
| --target | 只构建到指定阶段 | 调试中间阶段，发布时不要带 |
| --pull | 强制拉取基础镜像新版本 | 不加时可能一直用本地缓存的基础镜像 |
构建日志里标注 CACHED 的步骤是缓存命中，据此可以判断改动影响了哪些层；第一个非缓存步骤往下才是真正重新执行的部分。
上下文越大，构建开始前的传输与哈希越慢。用 .dockerignore 排除版本库目录、依赖目录、日志和构建产物，既提速也能避免敏感文件被复制进镜像。
构建失败时先看第一个报错，后面的错误往往是连锁反应；缓存命中的步骤不会重新执行，所以「本地能过、机器上不过」时要考虑缓存与基础镜像差异。
构建慢的常见原因
- 上下文太大：把依赖目录、版本库元数据、构建产物都传给了构建器，传输与哈希阶段就耗掉大部分时间
- 指令顺序不合理：源码复制放在安装依赖之前，改一行代码就重装全部依赖
- 安装与清理分离：包缓存留在上一层，既拖慢下载又让镜像体积虚高
- 基础镜像没有本地缓存：每次构建都重新拉取，网络差的环境尤其明显
- 没有跨机器缓存：流水线每次从零构建，可用缓存导入导出缓解
构建日志里的关键信息
| 日志内容 | 含义 | 怎么用 |
|---|---|---|
| 标注为已缓存的步骤 | 该层直接复用，未重新执行 | 确认改动影响范围，判断是否需要强制刷新 |
| 传输上下文大小 | 发给构建器的数据量 | 数值很大先检查排除文件配置 |
| 拉取基础镜像 | 基础镜像不在本地 | 统一基础镜像版本可减少这一步 |
| 错误出现在某一步 | 该指令执行失败 | 从第一个报错步骤开始排查，忽略后面的连锁错误 |
| 产物镜像标识 | 构建成功后的镜像名与摘要 | 摘要可用于部署时锁定不可变版本 |