Dockerfile 发行说明

此页面包含有关 Dockerfile 参考 中的新功能、改进、已知问题和错误修复的信息。

使用说明，请参阅 Dockerfile 前端语法 页面。

1.12.0

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.12.0

• 修复具有多个 ARG 指令的镜像配置历史记录行中描述不正确的问题。 moby/buildkit#5508

1.11.1

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.11.1

• 修复在同一 Dockerfile 内继承的阶段中使用 ONBUILD 指令时的回归问题。 moby/buildkit#5490

1.11.0

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.11.0

• 现在，ONBUILD 指令支持通过 from 引用其他构建阶段或镜像的命令，例如 COPY --from 或 RUN mount=from=...。 moby/buildkit#5357
• 已改进 SecretsUsedInArgOrEnv 构建检查，以减少误报。 moby/buildkit#5208
• 一项新的 InvalidDefinitionDescription 构建检查建议对构建参数和阶段描述中的注释进行格式化。这是一项 实验性检查。 moby/buildkit#5208， moby/buildkit#5414
• 针对 ONBUILD 指令的进度和错误处理进行了多项修复。 moby/buildkit#5397
• 改进了缺失标志错误的错误报告。 moby/buildkit#5369
• 增强了作为环境变量挂载的密钥值的进度输出。 moby/buildkit#5336
• 添加了内置构建参数 TARGETSTAGE，用于暴露当前构建的（最终）目标阶段名称。 moby/buildkit#5431

1.11.0-labs

• COPY --chmod 现在支持非八进制值。 moby/buildkit#5380

1.10.0

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.10.0

• 构建密钥 现在可以使用 env=VARIABLE 选项挂载为环境变量。 moby/buildkit#5215
• 现在，# check 指令允许使用新的实验性属性来启用实验性验证规则，例如 CopyIgnoredFile。 moby/buildkit#5213
• 改进对变量替换中不支持的修饰符的验证。 moby/buildkit#5146
• ADD 和 COPY 指令现在支持为 --chmod 选项值进行构建参数的变量插值。 moby/buildkit#5151
• 改进对 --chmod 选项在 COPY 和 ADD 指令中的验证。 moby/buildkit#5148
• 修复挂载中 size 和 destination 属性缺失的自动补全功能。 moby/buildkit#5245
• OCI 注解现已设置到 Dockerfile 前端发布镜像中。 moby/buildkit#5197

1.9.0

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.9.0

• 添加新的验证规则：
  • SecretsUsedInArgOrEnv
  • InvalidDefaultArgInFrom
  • RedundantTargetPlatform
  • CopyIgnoredFile（实验性）
  • FromPlatformFlagConstDisallowed
• 针对处理大型 Dockerfile 的多项性能改进。 moby/buildkit#5067, moby/buildkit#5029
• 修复在未定义构建阶段时构建 Dockerfile 可能引发的恐慌（panic）。 moby/buildkit#5150
• 修复了可能导致某些错误的 JSON 值在未产生错误的情况下通过的 JSON 解析问题。 moby/buildkit#5107
• 修复了一个回归问题，其中当目标路径为 . 时，COPY --link 可能会失败。 moby/buildkit#5080
• 修复在使用 Git URL 时对 ADD --checksum 的验证问题。 moby/buildkit#5085

1.8.1

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.8.1

错误修复和功能增强

• 修复变量展开时空字符串的处理问题。 moby/buildkit#5052
• 改进构建警告的格式。 moby/buildkit#5037, moby/buildkit#5045, moby/buildkit#5046
• 修复多阶段构建中 UndeclaredVariable 警告可能产生的无效输出问题。 moby/buildkit#5048

1.8.0

此版本的完整发布说明可在 GitHub 上查看。

# syntax=docker/dockerfile:1.8.0

• 已添加许多新的验证规则，以验证您的 Dockerfile 是否遵循最佳实践。这些规则会在构建过程中进行验证，并且可以使用新的 check 前端方法，仅触发验证而无需完成整个构建过程。
• 新指令 #check 和构建参数 BUILDKIT_DOCKERFILE_CHECK 让您能够控制行为或构建检查。 moby/buildkit#4962
• 现在会验证使用与预期平台不匹配的单平台基础镜像的情况。 moby/buildkit#4924
• 现在已正确处理全局作用域中展开 ARG 个定义时产生的错误。 moby/buildkit#4856
• 默认值 ARG 的展开现在仅在未被用户覆盖时才会发生。此前，展开操作会先完成，随后该值被忽略，这可能导致意外的展开错误。 moby/buildkit#4856
• 解析包含多个阶段的巨型 Dockerfile 的性能已得到提升。 moby/buildkit#4970
• 修复一些 Windows 路径处理的一致性问题。 moby/buildkit#4825

1.7.0

稳定版

# syntax=docker/dockerfile:1.7

• 变量扩展现在支持字符串替换和修剪。 moby/buildkit#4427, moby/buildkit#4287
• 具有本地源的命名上下文现在仅正确传输 Dockerfile 中使用的文件，而非整个源目录。 moby/buildkit#4161
• Dockerfile 现在能更好地验证构建阶段的顺序，如果阶段顺序不正确，会返回带有堆栈跟踪的友好错误信息。 moby/buildkit#4568, moby/buildkit#4567
• 历史提交消息现在包含了与 COPY 和 ADD 一起使用的标志。 moby/buildkit#4597
• 来自 Git 和 HTTP 源的 ADD 条命令的进度消息已得到改进。 moby/buildkit#4408

实验室

# syntax=docker/dockerfile:1.7-labs

• 新增 --parents 标志到 COPY，用于在复制文件时保留父目录结构。 moby/buildkit#4598, moby/buildkit#3001, moby/buildkit#4720, moby/buildkit#4728, 文档
• 新 --exclude 标志可用于 COPY 和 ADD 命令，以对复制的文件应用过滤。 moby/buildkit#4561, 文档

1.6.0

新

• 向 --start-interval 标志添加到 HEALTHCHECK 指令。

以下功能已从实验室渠道正式毕业并进入稳定版：

• ADD 指令现在可以 直接从 Git URL 导入文件
• ADD 指令现在支持 --checksum 标志 ，用于验证远程 URL 内容。

错误修复和功能增强

• 变量替换现在支持额外的兼容 POSIX 的变体，无需 :。 moby/buildkit#3611
• 导出的 Windows 镜像现在包含来自基础镜像的 OSVersion 和 OSFeatures 值。 moby/buildkit#3619
• 已将 Heredocs 的权限更改为 0644。 moby/buildkit#3992

1.5.2

错误修复和功能增强

• 修复从缺少分支名称但包含子目录的 Git 引用进行构建的问题
• 386 平台镜像现已包含在发布版本中

1.5.1

错误修复和功能增强

• 修复在多平台构建中出现警告条件时可能发生的恐慌（panic）

1.5.0（实验室）

新

• ADD 命令现在支持 --checksum 标志 用于验证远程 URL 内容

1.5.0

新

• ADD 命令现在可以 直接从 Git URL 导入文件

错误修复和功能增强

• 命名上下文现在支持 oci-layout:// 协议，用于从本地 OCI 布局结构中引入镜像。
• Dockerfile 现在支持辅助请求，用于列出所有构建目标或打印特定构建目标的接受参数概要。
• Dockerfile #syntax 指令（用于重定向到外部前端镜像） 现在允许该指令通过 // 注释或 JSON 进行设置。该文件 还可以包含 shebang 头部。
• 命名上下文现在可以使用空的 scratch 镜像进行初始化
• 命名上下文现在可以使用 SSH Git URL 进行初始化
• 修复导入 Schema1 镜像时对 ONBUILD 的处理

1.4.3

错误修复和功能增强

• 修复从名为docker-image://的上下文构建镜像时，创建时间戳未被重置的问题
• 修复在加载名为 docker-image:// 的上下文时，传递 FROM 命令的 --platform 标志的问题。

1.4.2

错误修复和功能增强

• 修复通过构建上下文传递的镜像中加载某些环境变量的问题

1.4.1

错误修复和功能增强

• 修复在输入为不同平台构建时，跨编译场景下基于输入的命名上下文解析问题

1.4.0

新

• COPY --link 和 ADD --link 允许在提高缓存效率的同时复制文件，并支持重新构建基础镜像而无需完全重建。--link 将文件复制到单独的层，然后利用新的 LLB MergeOp 实现将独立的层链接在一起。
• Heredocs 支持已从实验室频道提升至稳定版。此功能允许编写多行内联脚本和文件。
• 额外 命名的构建上下文 可以传递给构建命令，以添加或覆盖构建中的某个阶段或镜像。上下文的来源可以是本地源、镜像、Git 或 HTTP URL。
• BUILDKIT_SANDBOX_HOSTNAME 构建参数 可用于设置 RUN 步骤的默认主机名

错误修复和功能增强

• 使用交叉编译阶段时，步骤的目标平台现在会显示在进度输出中
• 修复某些情况下 Heredocs 错误地从内容中移除引号的问题

1.3.1

错误修复和功能增强

• 修复解析不带值的"required"挂载键的问题

1.3.0（实验室）

新

• RUN 和 COPY 命令现在支持 Here-document 语法 ，允许编写多行内联脚本和文件

1.3.0

新

• RUN 命令允许 --network 标志 用于请求特定类型的网络条件。--network=host 需要允许 network.host 授权。此功能此前 仅在实验室通道中可用

错误修复和功能增强

• ADD 命令在使用远程 URL 输入时，现在能正确处理 --chmod 标志
• 值适用于 RUN --mount 标志 现在支持变量扩展，但 from 字段除外
• 允许 BUILDKIT_MULTI_PLATFORM 构建参数 以强制始终创建多平台镜像，即使仅包含单个平台

1.2.1（实验室）

错误修复和功能增强

• RUN 命令允许 --network 标志 用于请求特定类型的网络条件。--network=host 需要允许 network.host 授权

1.2.1

错误修复和功能增强

• 还原“确保 ENTRYPOINT 命令至少有一个参数”
• 优化在多平台交叉编译构建中处理 COPY 次调用

1.2.0（实验室）

错误修复和功能增强

• 实验频道已重命名为 labs

1.2.0

新

• RUN --mount 语法用于创建秘密、SSH、绑定和缓存挂载的功能已移至主线通道
• ARG 命令 现在支持在同一行定义多个构建参数，类似于 ENV

错误修复和功能增强

• 元数据加载错误现在被视为致命错误，以避免构建结果不正确
• 允许使用小写的 Dockerfile 名称
• --chown 标志在 ADD 中现在支持参数扩展
• ENTRYPOINT 需要至少一个参数，以避免创建损坏的镜像

1.1.7

错误修复和功能增强

• 将 FrontendInputs 转发到网关

1.1.2（实验性）

错误修复和功能增强

• 允许为进程设置安全模式，值为 RUN --security=sandbox|insecure
• 允许为 缓存挂载 设置 uid/gid
• 避免请求将内部链接的路径拉取到构建上下文中
• 确保缺失的缓存 ID 默认为目标路径
• 允许通过 BUILDKIT_CACHE_MOUNT_NS 构建参数 为缓存挂载设置命名空间

1.1.2

错误修复和功能增强

• 使用正确的用户修复工作目录创建，且不要重置自定义所有权
• 修复对同时用作 ENV 的空构建参数的处理
• 检测循环依赖

1.1.0

新

• ADD/COPY 个命令现在支持基于 llb.FileOp 的实现，并且如果内置文件操作功能可用，则不再需要辅助镜像。
• --chown 标志现在支持用于 COPY 命令的变量扩展

错误修复和功能增强

• 为了查找构建上下文中被忽略的文件，Dockerfile 前端会首先寻找一个名为 <path/to/Dockerfile>.dockerignore 的文件；如果未找到该文件，则会在构建上下文的根目录中查找 .dockerignore 文件。这使得拥有多个 Dockerfile 的项目可以使用不同的 .dockerignore 定义。