基本语法
docker build [OPTIONS] PATH | URL | -
PATH: 构建上下文的路径，通常是包含Dockerfile和相关文件的本地目录。 表示当前目录。URL: 一个 Git 仓库的 URL，Docker 会克隆这个仓库并在其中寻找Dockerfile。- 从标准输入（stdin）读取
Dockerfile，这通常用于 CI/CD 管道中，直接将Dockerfile内容通过管道传递给docker build。
核心参数详解
下面我将参数分为几类,以便更好地理解和使用。
（图片来源网络，侵删）
指定构建上下文和 Dockerfile
这些参数告诉 Docker 从哪里寻找构建所需的文件。
| 参数 | 全称 | 描述 | 示例 |
|---|---|---|---|
-f, --file |
--file |
指定 Dockerfile 的路径。Dockerfile 不在构建上下文的根目录下，或者文件名不是 Dockerfile，就需要使用此参数。 |
docker build -f ./path/to/my/Dockerfile . |
--build-context |
--build-context |
(重要) 为构建添加一个额外的文件或目录作为上下文，这在需要将一些不在主上下文内的文件传递给构建过程时非常有用。 | docker build --build-context src=./extra_source_code . |
--target |
--target |
在 Dockerfile 中有多个 FROM 指令（多阶段构建）时，指定在哪个阶段停止构建并导出最终的镜像。 |
docker build --target builder . |
控制构建过程
这些参数用于在构建过程中传递信息、设置标签或管理缓存。
| 参数 | 全称 | 描述 | 示例 |
|---|---|---|---|
-t, --tag |
--tag |
为构建的镜像设置一个或多个标签（Repository:Tag 格式）。这是最常用的参数之一。 | docker build -t my-app:latest . docker build -t my-app:v1.0 -t my-registry.com/my-app:v1.0 . |
--label |
--label |
为镜像添加元数据标签（键值对）。 | docker build --label "com.example.vendor=MyCompany" . |
--build-arg |
--build-arg |
在构建时向 Dockerfile 传递变量，这些变量可以在 Dockerfile 中通过 ARG 指令使用。 |
docker build --build-arg VERSION=1.2.3 . docker build --build-arg HTTP_PROXY=http://proxy.example.com . |
--no-cache |
--no-cache |
禁用构建缓存，强制 Docker 重新执行所有指令，即使它们在之前的构建中已经存在，这对于确保使用最新的依赖或修复缓存问题很有用。 | docker build --no-cache . |
--pull |
--pull |
总是尝试拉取 FROM 指令中指定的基础镜像的最新版本，即使本地已经存在。 |
docker build --pull . |
高级与性能优化参数
这些参数用于更精细地控制构建过程,提高构建速度和效率。
| 参数 | 全称 | 描述 | 示例 |
|---|---|---|---|
--network |
--network |
设置构建过程中容器的网络模式，默认是 default，这对于在 RUN 指令中需要访问外部网络（如下载依赖）的场景很重要。 |
docker build --network host . docker build --network none . |
--shm-size |
--shm-size |
设置构建容器的 /dev/shm 分区的大小，对于需要大量共享内存的应用（如某些科学计算或测试框架）非常有用。 |
docker build --shm-size=1gb . |
--ulimit |
--ulimit |
设置构建容器的 ulimit 值，用于限制资源，如打开的文件描述符数量。 |
docker build --ulimit nofile=1024:2048 . |
--platform |
--platform |
指定目标平台的构建，这对于构建跨平台镜像（如 ARM64, AMD64）至关重要，尤其是在 buildx 构建多平台镜像时。 |
docker build --platform linux/amd64 . docker build --platform linux/arm64 . |
--progress |
--progress |
设置构建日志的输出格式。auto (默认), plain (简洁), tty (彩色进度条)。 |
docker build --progress=plain . |
--secret |
--secret |
在构建过程中安全地传递敏感信息（如 API 密钥、密码），这些信息不会存在于镜像的层中，只在 RUN 指令执行时可用。 |
docker build --secret id=mykey,src=./secret.txt . 在 Dockerfile 中使用: RUN --mount=type=secret,id=mykey cat /run/secrets/mykey |
--cache-from |
--cache-from |
指定一个或多个镜像作为构建缓存的来源，这对于 CI/CD 流水线非常有用，可以使用之前构建好的镜像作为缓存，加速后续构建。 | docker build --cache-from=my-app:latest . |
--cache-to |
--cache-to |
将构建的缓存推送到指定的镜像仓库中，通常与 --cache-from 配合使用，以构建一个缓存策略。 |
docker build --cache-to=type=registry,ref=my-app:cache . |
其他实用参数
| 参数 | 全称 | 描述 | 示例 |
|---|---|---|---|
--rm |
--rm |
构建成功后自动删除中间容器，这是默认行为。 | docker build --rm=true . (默认) docker build --rm=false . (保留中间容器，用于调试) |
--force-recreate |
--force-recreate** |
(注意：此参数是 docker-compose 的，不是 docker build 的) |
请勿在此处使用，在 docker build 中，要强制重建，请使用 --no-cache。 |
--quiet, -q |
--quiet |
静默模式，只输出最终的镜像 ID，不显示构建过程中的详细日志。 | docker build -q . |
--help |
--help |
显示帮助信息。 | docker build --help |
实战示例
示例 1：基本构建
在当前目录下,使用默认的 Dockerfile 构建一个名为 my-web-app，标签为 latest 的镜像。
（图片来源网络，侵删）
docker build -t my-web-app:latest .
示例 2：传递构建参数并指定 Dockerfile
使用 prod.Dockerfile 文件，并传递 NODE_ENV=production 变量。
docker build --file prod.Dockerfile --build-arg NODE_ENV=production -t my-web-app:prod .
示例 3：多阶段构建
Dockerfile 中包含多个 FROM 指令，我们只想构建到 builder 阶段并导出。
# stage 1: builder FROM golang:1.19 AS builder WORKDIR /app COPY . . RUN go build -o myapp . # stage 2: final FROM alpine:latest WORKDIR /root/ COPY --from=builder /app/myapp . CMD ["./myapp"]
构建命令：
# 默认会构建到最后一个阶段 docker build -t my-app:final . # 只构建到 builder 阶段 docker build --target builder -t my-app:builder .
示例 4：在 CI/CD 中使用 --cache-from
这是一个典型的 CI/CD 场景，每次构建都使用上一次构建的镜像作为缓存。
（图片来源网络，侵删）
# 假设 CI/CD 变量中设置了 DOCKER_USERNAME 和 DOCKER_PASSWORD echo $DOCKER_PASSWORD | docker login -u $DOCKER_USERNAME --password-stdin # 从远程仓库拉取缓存，构建并推送新镜像和缓存 docker build \ --cache-type=registry \ --cache-from=my-registry.com/my-app:cache \ --cache-to=my-registry.com/my-app:cache,mode=max \ -t my-registry.com/my-app:$(git rev-parse --short HEAD) .
示例 5：使用 --secret 传递敏感信息
这是一个更安全的做法,避免将密码硬编码在 Dockerfile 或构建参数中。
- 准备一个包含密钥的文件
api_key.txt。 - 在
Dockerfile中使用--mount=type=secret。
FROM alpine
RUN apk add --no-cache curl
# 在运行时挂载 secret 文件，并执行命令
RUN --mount=type=secret,id=my_api_key,mode=0444 \
curl -H "X-API-KEY: $(cat /run/secrets/my_api_key)" https://api.example.com/data
构建命令：
docker build --secret id=my_api_key,src=./api_key.txt -t my-app-with-secret .
掌握 docker build 参数是高效使用 Docker 的关键，初学者应重点掌握 -t, -f, --build-arg 和 --no-cache，随着经验的增长，--target, --platform, --secret 和 --cache-from/--cache-to 等高级参数将帮助你构建更安全、更高效、更可维护的 Docker 镜像。
