Docker Build（旧版构建器）

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

描述

重要
本页引用了docker build, 使用旧版（pre-BuildKit）构建后端。仅当您正在构建 Windows 容器时，此配置才相关。
有关默认docker build、使用 Buildx、看docker buildx build.

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

使用docker build默认使用 Buildx（和 BuildKit），除非：

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

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

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

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

$ docker build .

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

因此，在使用旧版构建器时，您请仔细考虑在指定的上下文中包括哪些文件。使用.dockerignorefile 从中排除构建中不需要的文件和目录作为 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 上下文。重用前面的示例，路径COPY ../../some-dir .计算结果为COPY some-dir .使用 BuildKit。

选项

选择	违约	描述
`--add-host`		添加自定义主机到 IP 映射（`host:ip`)
`--build-arg`		设置构建时变量
`--cache-from`		要考虑作为缓存源的镜像
`--cgroup-parent`		为`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 容器时，此选项非常有用窗户。这--isolation=<value>option 设置容器的隔离科技。在 Linux 上，唯一支持的是default选项，它使用 Linux 命名空间。在 Microsoft Windows 上，您可以指定以下值：

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

指定--isolationflag 与设置--isolation="default".

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

此标志仅在 Windows 上运行的守护程序上受支持，并且仅支持这credentialspec选择。这credentialspec必须采用file://spec.txt或registry://keyname.

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

概述

注意
这--squashoption 是一项实验性功能，不应考虑稳定。

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

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

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

已知限制

这--squashoption 具有许多已知限制：

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

先决条件

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

您可以使用--experimental启动时的标志 Docker 守护程序或设置experimental: true在daemon.json配置文件。

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

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`旗

以下是使用--squash旗。下面是Dockerfile:

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

接下来，构建一个名为test使用--squash旗。

$ docker build --squash -t test .

构建完成后，历史记录如下所示。历史记录可以显示层的 name 为<missing>，并且有一个带有 COMMENT 的新图层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_me既然消失了，请确保hello\nworld是在/hello，请确保HELLO环境变量的值为world.