Dockerfile 发布说明
本页面包含关于 Dockerfile 参考 中的新特性、改进、已知问题和 bug 修复的信息。
有关用法,请参阅Dockerfile 前端语法页面。
1.15.0
2025-04-15此版本的完整发布说明可在 GitHub 上查看。
# syntax=docker/dockerfile:1.15.0
- 无效目标的构建错误现在会显示正确可能名称的建议。 moby/buildkit#5851
- 修复了 SBOM 证明在 Windows 目标上产生错误的问题。 moby/buildkit#5837
- 修复了处理大纲请求时递归
ARG
导致无限循环的问题。 moby/buildkit#5823 - 修复了从 JSON 解析语法指令时,如果 JSON 中包含非字符串数据类型,会导致解析失败的问题。 moby/buildkit#5815
- 修复了镜像配置中的平台格式非规范化问题(1.12 版本回归)。 moby/buildkit#5776
- 修复了使用 WCOW 时,复制到目标目录但目录不存在时会出错的问题。 moby/buildkit#5249
1.14.1
2025-03-05此版本的完整发布说明可在 GitHub 上查看。
# syntax=docker/dockerfile:1.14.1
- 规范化镜像配置中的平台。 moby/buildkit#5776
1.14.0
2025-02-19此版本的完整发布说明可在 GitHub 上查看。
# syntax=docker/dockerfile:1.14.0
COPY --chmod
现在允许非八进制值。此功能以前在 labs 通道中,现已在主版本中提供。 moby/buildkit#5734- 修复了基础镜像设置 OSVersion 平台属性时的处理问题。 moby/buildkit#5714
- 修复了命名上下文元数据即使当前构建配置无法访问也能被解析,从而导致构建错误的问题。 moby/buildkit#5688
1.14.0 (labs)
2025-02-19重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
此版本的完整发布说明可在 GitHub 上查看。
# syntax=docker.io/docker/dockerfile-upstream:1.14.0-labs
- 新的
RUN --device=name,[required]
标志允许构建请求 CDI 设备在构建步骤中可用。需要 BuildKit v0.20.0+ moby/buildkit#4056, moby/buildkit#5738
1.13.0
2025-01-20此版本的完整发布说明可在 GitHub 上查看。
# syntax=docker/dockerfile:1.13.0
- 新增
TARGETOSVERSION
、BUILDOSVERSION
内置构建参数,适用于 Windows 构建。TARGETPLATFORM
值现在也包含OSVersion
值。moby/buildkit#5614 - 允许以字节顺序标记 (BOM) 开头的文件进行外部前端的语法转发。moby/buildkit#5645
- Windows 容器中的默认
PATH
已更新,包含powershell.exe
目录。moby/buildkit#5446 - 修复 Dockerfile 指令解析,不再允许无效语法。moby/buildkit#5646
- 修复了在继承阶段
ONBUILD
命令可能运行两次的情况。moby/buildkit#5593 - 修复 Dockerfile 中子阶段可能丢失命名上下文替换的问题。moby/buildkit#5596
1.13.0 (labs)
2025-01-20重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
此版本的完整发布说明可在 GitHub 上找到。
# syntax=docker.io/docker/dockerfile-upstream:1.13.0-labs
- 修复对
COPY --chmod
非八进制值支持的问题。moby/buildkit#5626
1.12.0
2024-11-27此版本的完整发布说明可在 GitHub 上找到。
# syntax=docker/dockerfile:1.12.0
- 修复图像配置历史记录中包含多个
ARG
指令时描述不正确的问题。moby/buildkit#5508
1.11.1
2024-11-08此版本的完整发布说明可在 GitHub 上找到。
# syntax=docker/dockerfile:1.11.1
- 修复在使用
ONBUILD
指令时,同一 Dockerfile 中继承阶段出现的回归问题。moby/buildkit#5490
1.11.0
2024-10-30此版本的完整发布说明可在 GitHub 上找到。
# syntax=docker/dockerfile:1.11.0
ONBUILD
指令现在支持引用其他阶段或图像的命令,例如COPY --from
或RUN mount=from=...
。moby/buildkit#5357SecretsUsedInArgOrEnv
构建检查已改进,以减少误报。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)
重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
COPY --chmod
现在支持非八进制值。moby/buildkit#5380
1.10.0
2024-09-10此版本的完整发布说明可在 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- 改进了对
COPY
和ADD
指令中--chmod
选项的验证。moby/buildkit#5148 - 修复了挂载点大小和目标属性可能缺失自动完成的问题。moby/buildkit#5245
- OCI 注解现在被设置到 Dockerfile 前端发布镜像中。moby/buildkit#5197
1.9.0
2024-07-11此版本的完整发布说明可在 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 - 修复了当
ADD --checksum
与 Git URL 一起使用时的验证问题。moby/buildkit#5085
1.8.1
2024-06-18此版本的完整发布说明可在 GitHub 上找到。
# syntax=docker/dockerfile:1.8.1
Bug 修复和增强功能
- 修复了变量扩展中空字符串的处理问题。moby/buildkit#5052
- 改进了构建警告的格式。moby/buildkit#5037, moby/buildkit#5045, moby/buildkit#5046
- 修复了多阶段构建中
UndeclaredVariable
警告可能产生无效输出的问题。moby/buildkit#5048
1.8.0
2024-06-11此版本的完整发布说明可在 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
2024-03-06稳定版
# 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 - 改进了
ADD
命令从 Git 和 HTTP 源获取时的进度消息。moby/buildkit#4408
实验室功能
# syntax=docker/dockerfile:1.7-labs
COPY
命令新增了--parents
标志,用于在复制文件时保留父目录结构。moby/buildkit#4598, moby/buildkit#3001, moby/buildkit#4720, moby/buildkit#4728, docsCOPY
和ADD
命令新增了--exclude
标志,可用于对复制的文件应用过滤器。moby/buildkit#4561, docs
1.6.0
2023-06-13新增
- 为
HEALTHCHECK
指令添加了--start-interval
标志。
以下功能已从实验室通道升级到稳定版
ADD
指令现在可以直接从 Git URL 导入文件ADD
指令现在支持--checksum
标志,用于验证远程 URL 内容的完整性。
Bug 修复和增强功能
- 变量替换现在支持其他不带
:
的 POSIX 兼容变体。moby/buildkit#3611 - 导出的 Windows 镜像现在包含来自基础镜像的 OSVersion 和 OSFeatures 值。moby/buildkit#3619
- 将 Heredocs 的权限更改为 0644。moby/buildkit#3992
1.5.2
2023-02-14Bug 修复和增强功能
- 修复了从缺少分支名称但包含子目录的 Git 引用进行构建的问题。
- 版本中现在包含 386 平台镜像。
1.5.1
2023-01-18Bug 修复和增强功能
- 修复了多平台构建中出现警告情况时可能发生的 panic 问题。
1.5.0 (labs)
2023-01-10重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
新增
ADD
命令现在支持--checksum
标志,用于验证远程 URL 内容的完整性。
1.5.0
2023-01-10新增
ADD
命令现在可以直接从 Git URL 导入文件。
Bug 修复和增强功能
- 命名上下文现在支持
oci-layout://
协议,用于包含来自本地 OCI 布局结构的镜像。 - Dockerfile 现在支持二级请求,用于列出所有构建目标或打印特定构建目标的接受参数大纲。
- Dockerfile 的
#syntax
指令用于重定向到外部前端镜像,现在该指令也可以通过//
注释或 JSON 进行设置。文件还可以包含 shebang header(Shebang 头)。 - 命名上下文现在可以使用空的 scratch 镜像进行初始化。
- 命名上下文现在可以使用 SSH Git URL 进行初始化。
- 修复了导入 Schema1 镜像时处理
ONBUILD
的问题。
1.4.3
2022-08-23Bug 修复和增强功能
- 修复了从
docker-image://
命名上下文构建镜像时创建时间戳未重置的问题。 - 修复了加载
docker-image://
命名上下文时传递FROM
命令的--platform
标志的问题。
1.4.2
2022-05-06Bug 修复和增强功能
- 修复了从随构建上下文传递的镜像加载某些环境变量的问题。
1.4.1
2022-04-08Bug 修复和增强功能
- 修复了当输入是为不同平台构建时,交叉编译情况下命名上下文的解析问题。
1.4.0
2022-03-09新增
COPY --link
和ADD --link
允许以更高的缓存效率复制文件,并可以在不重建镜像的情况下重新基于镜像。--link
将文件复制到单独的层,然后使用新的 LLB MergeOp 实现将独立的层链接在一起。- Heredocs 支持已从实验室通道升级到稳定版。此功能允许编写多行内联脚本和文件。
- 可以将额外的命名构建上下文传递给构建,以在构建中添加或覆盖阶段或镜像。上下文的源可以是本地源、镜像、Git 或 HTTP URL。
BUILDKIT_SANDBOX_HOSTNAME
build-arg(构建参数)可用于设置RUN
步骤的默认主机名。
Bug 修复和增强功能
- 使用交叉编译阶段时,现在可以在进度输出中看到步骤的目标平台。
- 修复了 Heredocs 错误地从内容中删除引号的一些情况。
1.3.1
2021-10-04Bug 修复和增强功能
- 修复了解析不带值的 "required" mount key(挂载键)的问题。
1.3.0 (labs)
2021-07-16重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
新增
RUN
和COPY
命令现在支持Here-document 语法,允许编写多行内联脚本和文件。
1.3.0
2021-07-16新增
RUN
命令允许使用--network
标志来请求特定类型的网络条件。--network=host
需要允许network.host
授权。此功能以前仅在实验室通道中可用。
Bug 修复和增强功能
- 带有远程 URL 输入的
ADD
命令现在可以正确处理--chmod
标志。 - 为
RUN --mount
标志提供的值现在支持变量展开,但from
字段除外。 - 允许使用
BUILDKIT_MULTI_PLATFORM
build arg(构建参数)来强制始终创建多平台镜像,即使只包含单一平台。
1.2.1 (labs)
2020-12-12重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
Bug 修复和增强功能
RUN
命令允许使用--network
标志来请求特定类型的网络条件。--network=host
需要允许network.host
授权。
1.2.1
2020-12-12Bug 修复和增强功能
- 恢复了 "确保 ENTRYPOINT 命令至少有一个参数" 的更改。
- 优化了在多平台交叉编译构建中处理
COPY
调用的性能。
1.2.0 (labs)
2020-12-03重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
Bug 修复和增强功能
- Experimental 通道已重命名为 labs。
1.2.0
2020-12-03新增
- 用于创建 secret、ssh、bind 和 cache mounts 的
RUN --mount
语法已移至 mainline 通道。 ARG
命令现在支持在一行上定义多个构建参数,类似于ENV
。
Bug 修复和增强功能
- 元数据加载错误现在被视为致命错误处理,以避免错误的构建结果。
- 允许使用小写 Dockerfile 名称。
ADD
命令中的--chown
标志现在允许参数展开。ENTRYPOINT
需要至少一个参数,以避免创建损坏的镜像。
1.1.7
2020-04-18Bug 修复和增强功能
- 将
FrontendInputs
转发到网关。
1.1.2 (labs)
2019-07-31重要
labs 通道提供了访问稳定通道中尚未提供的实验性 Dockerfile 功能的权限。
Bug 修复和增强功能
- 允许使用
RUN --security=sandbox|insecure
为进程设置安全模式。 - 允许为cache mounts(缓存挂载)设置 uid/gid。
- 避免请求将内部链接的路径拉取到构建上下文。
- 确保缺失的缓存 ID 默认为目标路径。
- 允许使用
BUILDKIT_CACHE_MOUNT_NS
build arg(构建参数)为缓存挂载设置命名空间。
1.1.2
2019-07-31Bug 修复和增强功能
- 修复了使用正确用户创建工作目录的问题,且不重置自定义所有权。
- 修复了处理也用作
ENV
的空构建参数的问题。 - 检测循环依赖。
1.1.0
2019-04-27新增
ADD/COPY
命令现在支持基于llb.FileOp
的实现,并且如果内置文件操作支持可用,则不需要 helper image(辅助镜像)。COPY
命令的--chown
标志现在支持变量展开。
Bug 修复和增强功能
- 为了找到构建上下文中忽略的文件,Dockerfile 前端会首先查找文件
<path/to/Dockerfile>.dockerignore
,如果未找到,则会从构建上下文的根目录查找.dockerignore
文件。这使得包含多个 Dockerfile 的项目可以使用不同的.dockerignore
定义。