Docker Build（旧版构建器）

描述	从 Dockerfile 构建镜像
用法	`docker image build [OPTIONS] PATH \| URL \| -`
别名	`docker image build` `docker build` `docker builder build`

描述

重要
本页引用了的旧版实现 ，使用旧版（pre-BuildKit）构建后端。仅当您正在构建 Windows 容器时，此配置才相关。docker build
有关使用 Buildx 的 default 的信息，请参阅 Docker BuildX Build。docker build

使用旧版构建器进行构建时，镜像是通过 Dockerfile 创建的运行一系列提交。这个过程是与使用 BuildKit 相比，效率低下且速度慢，这就是为什么这个构建策略对于除构建 Windows 之外的所有用例都已弃用器皿。它对于构建 Windows 容器仍然很有用，因为 BuildKit 尚未为 Windows 提供完整的功能奇偶校验。

默认情况下，使用 Buildx（和 BuildKit）调用的构建，除非：docker build

您正在 Windows 容器模式下运行 Docker Engine
您可以通过设置环境变量 .DOCKER_BUILDKIT=0

本页的描述仅涵盖旧版生成器，以及旧版生成器中的行为偏离行为。有关常见功能和标志的信息在旧版构建器和 BuildKit 之间，例如和，请参阅到 Docker BuildX Build 的文档。--tag--target

使用旧版构建器构建上下文

构建上下文是您在调用构建时传递的位置参数命令。在下面的示例中，上下文为，表示当前 working 目录中。.

$ docker build .

当使用旧版构建器时，构建上下文被发送到完整。使用 BuildKit，只有您在构建中使用的文件是传播。旧版构建器不会计算它需要哪些文件事先。这意味着，对于具有大型上下文的构建，上下文传输可能需要很长时间，即使您只使用所包含文件的子集在上下文中。

因此，在使用旧版构建器时，您请仔细考虑在指定的上下文中包括哪些文件。使用 .dockerignore 文件从中排除构建中不需要的文件和目录作为 build 上下文的一部分发送。

访问构建上下文之外的路径

如果您尝试访问使用 Dockerfile 中的相对路径构建上下文。

FROM alpine
COPY ../../some-dir .

$ docker build .
...
Step 2/2 : COPY ../../some-dir .
COPY failed: forbidden path outside the build context: ../../some-dir ()

另一方面，BuildKit 会剥离遍历外部的 leading relative paths 的 build 上下文。重复使用前面的示例，路径的计算结果为 BuildKit。COPY ../../some-dir .COPY some-dir .

选项

选择	违约	描述
`--add-host`		添加自定义主机到 IP 映射（`host:ip`)
`--build-arg`		设置构建时变量
`--cache-from`		要考虑作为缓存源的镜像
`--cgroup-parent`		在构建过程中为说明设置父 cgroup`RUN`
`--compress`		使用 gzip 压缩构建上下文
`--cpu-period`		限制 CPU CFS （Completely Fair Scheduler）周期
`--cpu-quota`		限制 CPU CFS （Completely Fair Scheduler）配额
`-c, --cpu-shares`		CPU 份额（相对权重）
`--cpuset-cpus`		允许执行的 CPU （0-3， 0,1）
`--cpuset-mems`		允许在其中执行的 MEM （0-3， 0,1）
`--disable-content-trust`	`true`	跳过镜像验证
`-f, --file`		Dockerfile 的名称（默认值为`PATH/Dockerfile`)
`--force-rm`		始终移除中间容器
`--iidfile`		将镜像 ID 写入文件
`--isolation`		容器隔离技术
`--label`		设置镜像的元数据
`-m, --memory`		内存限制
`--memory-swap`		交换限制等于内存加上交换：-1 启用无限交换
`--network`		API 1.25+在构建过程中设置 RUN 指令的联网模式
`--no-cache`		构建镜像时不要使用缓存
`--platform`		API 1.38+如果服务器支持多平台，则设置 platform
`--pull`		始终尝试提取较新版本的镜像
`-q, --quiet`		成功时禁止生成输出并打印镜像 ID
`--rm`	`true`	成功构建后删除中间容器
`--security-opt`		安全选项
`--shm-size`		大小`/dev/shm`
`--squash`		API 1.25+ 实验性（守护进程）：将新构建的层压缩到单个新层中
`-t, --tag`		Name 和格式为`name:tag`
`--target`		将目标 build 阶段设置为 build。
`--ulimit`		Ulimit 选项

例子

指定容器的隔离技术（--isolation）

当您在 Docker 容器上运行 Docker 容器时，此选项非常有用窗户。该选项设置容器的隔离科技。在 Linux 上，唯一支持的是使用 Linux 命名空间。在 Microsoft Windows 上，您可以指定以下值：--isolation=<value>default

价值	描述
`default`	使用 Docker 守护程序的 .如果未指定隔离技术，则 Microsoft Windows 将使用其默认值。`--exec-optdaemonprocess`
`process`	仅限命名空间隔离。
`hyperv`	Hyper-V 虚拟机管理程序基于分区的隔离。

指定不带值的标志与设置相同。--isolation--isolation="default"

可选安全选项（--security-opt）

此标志仅在 Windows 上运行的守护程序上受支持，并且仅支持选项。必须采用或 .credentialspeccredentialspecfile://spec.txtregistry://keyname

压缩镜像的图层（--squash）（实验性）

概述

注意
该选项是一项实验性功能，不应考虑稳定。--squash

构建镜像后，此标志会将新层压缩到新镜像中，其中包含单个新图层。压缩不会破坏任何现有镜像，而是使用压缩图层的内容创建新镜像。这有效地使所有命令看起来都是使用单个图层创建的。该标志保留构建缓存。Dockerfile--squash

如果您的 Dockerfile 生成多个层，则压缩层可能是有益的修改相同的文件。例如，在一个步骤中创建的文件和在另一个步骤中删除。对于其他用例，压缩镜像实际上可能具有对性能的负面影响。拉取由多个层，守护进程可以并行拉取层，并允许在镜像（节省空间）。

对于大多数用例，多阶段构建是更好的选择，因为它们提供了更多对构建进行精细控制，并可以利用 future 构建器中的优化。请参阅 Multi-stage builds 部分以了解更多信息。

已知限制

该选项具有许多已知限制：--squash

压缩图层时，生成的镜像无法利用图层与其他镜像共享，并且可能会占用更多空间。共享基础镜像仍受支持。
使用此选项时，您可能会看到由于以下原因而使用的空间明显增加存储镜像的两个副本，一个用于包含所有缓存的构建缓存层，一个用于压扁版本。
虽然挤压图层可能会生成较小的镜像，但它可能会产生负面的对性能的影响，因为单个层的提取时间更长，以及您无法并行下载单个层。
尝试压缩未更改 filesystem（例如，Dockerfile 仅包含指令）， Squash 步骤将失败（请参阅问题 #33823）。ENV

先决条件

本页的示例是在 Docker 23.03 中使用实验模式。

您可以在启动时使用 flag 来启用实验模式 Docker 守护程序或配置中的设置文件。--experimentalexperimental: truedaemon.json

默认情况下，实验模式处于禁用状态。要查看的当前配置 Docker 守护程序中，使用命令并检查该部分中的行：docker versionExperimentalEngine

Client: Docker Engine - Community
 Version:           23.0.3
 API version:       1.42
 Go version:        go1.19.7
 Git commit:        3e7cbfd
 Built:             Tue Apr  4 22:05:41 2023
 OS/Arch:           darwin/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          23.0.3
  API version:      1.42 (minimum version 1.12)
  Go version:       go1.19.7
  Git commit:       59118bf
  Built:            Tue Apr  4 22:05:41 2023
  OS/Arch:          linux/amd64
  Experimental:     true
 [...]

使用 `--squash` 标志构建镜像

以下是带有该标志的构建示例。下面是：--squashDockerfile

FROM busybox
RUN echo hello > /hello
RUN echo world >> /hello
RUN touch remove_me /remove_me
ENV HELLO=world
RUN rm /remove_me

接下来，构建一个使用 flag 命名的镜像。test--squash

$ docker build --squash -t test .

构建完成后，历史记录如下所示。历史记录可以显示层的 name 为，并且有一个带有 COMMENT 的新图层。<missing>merge

$ docker history test

IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
4e10cb5b4cac        3 seconds ago                                                       12 B                merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb
<missing>           5 minutes ago       /bin/sh -c rm /remove_me                        0 B
<missing>           5 minutes ago       /bin/sh -c #(nop) ENV HELLO=world               0 B
<missing>           5 minutes ago       /bin/sh -c touch remove_me /remove_me           0 B
<missing>           5 minutes ago       /bin/sh -c echo world >> /hello                 0 B
<missing>           6 minutes ago       /bin/sh -c echo hello > /hello                  0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) CMD ["sh"]                    0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff   1.113 MB

测试镜像，检查是否消失，确保在中，确保环境变量的值为。/remove_mehello\nworld/helloHELLOworld