Docker build 命令详解与实战笔记

摘要：docker build 是日常打包镜像最常用的命令，很多人容易搞混构建上下文、BuildKit、buildx、缓存、多阶段构建这些概念，本文整理常用参数、踩坑点和生产可用命令。

一、基础说明

docker build 的作用：读取 Dockerfile，基于构建上下文（context）打包生成 Docker 镜像。 新版本 Docker 默认底层启用 BuildKit，多平台构建推荐使用 buildx。

基础语法

docker build [OPTIONS] PATH | URL | -

最简示例

# . 代表把当前目录作为构建上下文，目录内需要存在 Dockerfile
docker build -t myapp:v1 .

• -t：给镜像打标签，格式 镜像名:版本；支持多次 -t，一次性打上多个标签。

二、高频参数速查

# -f / --file：指定自定义名称的 Dockerfile
docker build -t myapp:v1 -f Dockerfile.prod .

# --build-arg：传入构建参数，Dockerfile 内通过 ARG 接收，仅构建阶段生效，不会成为镜像环境变量
docker build -t myapp:v1 --build-arg VERSION=1.0 --build-arg ENV=prod .

# --no-cache：关闭构建缓存，全部步骤重新执行，适合依赖更新后强制全量构建
docker build -t myapp:v1 --no-cache .

# --cache-from：复用远端镜像缓存，CI流水线里非常常用，大幅提升打包速度
docker build -t myapp:v1 --cache-from myapp:cache .

# --target：多阶段构建，只构建到指定阶段，常用于单独编译、导出构建产物
docker build -t myapp:builder --target builder .

# --network：指定 RUN 执行时的网络，--network=host 直接复用宿主机网络
docker build -t myapp:v1 --network host .

三、核心概念：构建上下文 context

命令最后的 . 不是 Dockerfile 的路径，是构建上下文目录。 COPY、ADD 指令只能读取上下文里面的文件，无法读取上下文之外的宿主机文件。

⚠️ 最佳实践： 不要把根目录、超大目录作为上下文，文件越多，上传到 Docker 守护进程的速度越慢。 配合 .dockerignore 过滤不需要参与构建的文件。

.dockerignore 参考模板

.git
node_modules
*.log
.env
.DS_Store

四、buildx 多平台构建（现代推荐用法）

现在 docker build 底层等价于 docker buildx build，跨架构打包镜像（amd64 /arm64）必须用 buildx。

# 单平台构建，--load 把镜像加载到本地 docker images 列表
docker buildx build -t myapp:v1 --platform linux/amd64 --load .

# 多平台同时构建并直接推送到镜像仓库，不会在本地留存镜像
docker buildx build -t registry.example.com/myapp:v1 --platform linux/amd64,linux/arm64 --push .

五、高频踩坑清单

1. COPY 提示找不到文件：待复制文件不在构建上下文内；
2. 构建速度极慢：上下文目录过大，缺少 .dockerignore；
3. ARG 参数不生效：多阶段构建中，ARG 写在 FROM 之后，每个阶段需要单独声明；
4. 缓存意外失效：RUN 命令内容变更、COPY 的文件哈希发生变化，缓存链直接断开。

六、生产环境可直接复制的命令

docker build -t myapp:latest -t myapp:v1.0.0 \
  -f Dockerfile \
  --build-arg BUILD_TIME=$(date +%s) \
  --cache-from myapp:cache \
  .

小结

docker build 看着简单，但上下文、缓存、buildx 是生产打包的核心。用好 .dockerignore、--cache-from、多阶段构建，既能减小镜像体积，又能大幅节约 CI 打包耗时。