Docker build 命令教程：参数说明与示例

docker build 根据 Dockerfile 构建镜像。Dockerfile 的写法请参见 Dockerfile 入门 和 Dockerfile 指令大全，本页整理了命令本身的参数。

语法

docker build [参数] 构建上下文路径

最常见的形式：

docker build -t myapp:1.0 .

-t 用于命名镜像，最后的 . 是构建上下文（build context）：当前文件夹中的文件会交给构建程序，默认也从这里读取 Dockerfile。docker build、docker buildx build 和 docker image build 是同一个命令。

常用参数

运行 docker build --help 可以查看完整列表。

示例项目

以下示例都使用这个多阶段 Dockerfile：

FROM alpine:3.23 AS base
ARG GREETING=hello
RUN echo "$GREETING from build" > /greeting.txt

FROM base AS test
RUN cat /greeting.txt && echo "tests passed"

FROM base
CMD ["cat", "/greeting.txt"]

另外还有一个 Dockerfile.dev，内容只有 FROM alpine:3.23 和 CMD ["echo", "dev image"]。

-t：构建并命名

$ docker build -t greet .

[+] Building 0.6s (6/6) FINISHED                                                                                                       docker:default
 => [internal] load build definition from Dockerfile                                                                                             0.0s
 => => transferring dockerfile: 235B                                                                                                             0.0s
 => [internal] load metadata for docker.io/library/alpine:3.23                                                                                   0.1s
 => [internal] load .dockerignore                                                                                                                0.0s
 => => transferring context: 2B                                                                                                                  0.0s
 => CACHED [base 1/2] FROM docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                 0.0s
 => => resolve docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                             0.0s
 => [base 2/2] RUN echo "hello from build" > /greeting.txt                                                                                       0.3s
 => exporting to image                                                                                                                           0.1s
 => => exporting layers                                                                                                                          0.0s
 => => exporting manifest sha256:0d0e8696cb61970ffeebe21706f795d44bb7fdb22662a328bd83a22c9cb91d60                                                0.0s
 => => exporting config sha256:04f0467aef1baf360852e9f8633e676c7cbbcbe454d0827bbdd474dcda4a7d1f                                                  0.0s
 => => exporting attestation manifest sha256:186d1197793b26cefb32e3555067d8caaa7d626310efb2c1eeb6c42bfefb01a1                                    0.0s
 => => exporting manifest list sha256:2632bf33adbcb3cffc3697245d5e0ad0d239b58b46413d39f87e29cbbebfb3ef                                           0.0s
 => => naming to docker.io/library/greet:latest                                                                                                  0.0s
 => => unpacking to docker.io/library/greet:latest                                                                                               0.0s

$ docker run --rm greet
hello from build

[base 2/2] 表示这是 base 阶段的第 2 步。test 阶段没有构建：未指定 --target 时，只构建最后一个阶段及其依赖阶段。

--build-arg：传入构建参数

$ docker build -q --build-arg GREETING=hi -t greet:hi .
sha256:c6f108c2247535f2ee548ef5868bdf83911f06e7ecfeab0fb58eb47b19c79154

$ docker run --rm greet:hi
hi from build

GREETING 的默认值是 hello，用 --build-arg GREETING=hi 覆盖后，构建出的文件内容就变成了 hi from build。ARG 只在构建时存在，不要用它传递密码（原因见 安全最佳实践）。

-f：指定 Dockerfile

$ docker build -q -f Dockerfile.dev -t greet:dev .
sha256:59849c87b388414a149e72c98ff88d30d9b575f5240625c0b8f58332ce5103fb

$ docker run --rm greet:dev
dev image

同一个项目可以有多个 Dockerfile，例如 Dockerfile.dev、Dockerfile.prod。注意，-f 只决定读取哪个 Dockerfile，构建上下文仍然是最后的 .。

--target 与 --progress plain：只构建测试阶段并查看完整输出

$ docker build --target test --progress plain --no-cache . 2>&1 | grep -E "^#[0-9]+ [0-9.]+ |DONE|ERROR" | grep -v DONE
#6 0.210 hello from build
#6 0.210 tests passed

• --target test 只构建到 test 阶段，常用于在 CI 中运行测试。
• --progress plain 显示 RUN 命令的完整输出（hello from build、tests passed）。默认输出模式会在步骤成功后折叠输出。
• --no-cache 确保 RUN 确实重新执行，而不是使用缓存。
• 这里用 grep 只保留 RUN 的输出行；#6 0.210 表示第 6 个步骤，开始后 0.210 秒。

结果

$ docker build -q --target base -t greet:base .
sha256:b92f520e3598da9bcb7ceb2cf82977090316062325363faae1d65c3630423b8e

$ docker images greet
IMAGE          ID             DISK USAGE   CONTENT SIZE   EXTRA
greet:base     b92f520e3598       12.9MB         3.85MB        
greet:dev      59849c87b388       12.9MB         3.85MB        
greet:hi       c6f108c22475       12.9MB         3.85MB        
greet:latest   2632bf33adbc       12.9MB         3.85MB

四个镜像大小相同，因为它们都只是在 Alpine 上添加了一个小文件。

其他常用写法

# 同时添加两个名称
docker build -t myapp:1.2.0 -t myapp:latest .

# 构建上下文是子文件夹，Dockerfile 在其他位置
docker build -f docker/Dockerfile.prod -t myapp ./src

# 重新下载基础镜像并且不使用缓存（完全重建）
docker build --pull --no-cache -t myapp .

# 为 amd64 服务器构建（在 Apple Silicon Mac 上）
docker build --platform linux/amd64 -t myapp .

# 构建时使用机密信息
docker build --secret id=npm_token,env=NPM_TOKEN -t myapp .

相关章节

• Dockerfile 入门、Dockerfile 指令大全
• 构建缓存与优化：缓存的工作方式
• 多阶段构建：--target 的更多用法
• 多平台镜像：--platform
• 常见错误信息：排查构建失败

动手练习

练习：使用本页的 Dockerfile，构建一个 GREETING 为 hey 的镜像，并同时命名为 greet:hey 和 greet:latest。

docker build --build-arg GREETING=hey -t greet:hey -t greet:latest .
docker run --rm greet:latest

更新于 2026年10月14日