自定义 Dockerfile 语法

Dockerfile 前端

BuildKit 支持从容器镜像动态加载前端。要使用外部 Dockerfile 前端，Dockerfile 的第一行需要设置 Dockerfile 指向您要使用的特定镜像的 syntax 指令：

# syntax=[remote image reference]

例如：

# syntax=docker/dockerfile:1
# syntax=docker.io/docker/dockerfile:1
# syntax=example.com/user/repo:tag@sha256:abcdef...

你还可以使用预定义的 BUILDKIT_SYNTAX 构建参数在命令行中设置前端镜像引用：

$ docker build --build-arg BUILDKIT_SYNTAX=docker/dockerfile:1 .

这定义了用于构建Dockerfile的Dockerfile语法的位置。BuildKit后端允许无缝使用作为Docker镜像分发并在容器沙箱环境中执行的外部实现。

自定义 Dockerfile 实现允许您：

• 无需更新 Docker 守护程序即可自动获取错误修复
• 确保所有用户都使用相同的实现来构建Dockerfile
• 在不更新 Docker 守护程序的情况下使用最新功能
• 在新功能或第三方功能集成到 Docker 守护程序之前，先试用这些功能
• 使用 替代构建定义，或创建您自己的
• 构建带有自定义功能的 Dockerfile 前端

注意

BuildKit 随附内置的 Dockerfile 前端，但建议使用外部镜像，以确保所有用户在构建器上使用相同版本，并且无需等待 BuildKit 或 Docker Engine 的新版本即可自动获取错误修复。

官方发布

Docker 在 Docker Hub 上的 docker/dockerfile 仓库中分发官方版本的镜像，可用于构建 Dockerfile。新镜像的发布有两个渠道： stable 和 labs。

稳定通道

stable 遵循 语义版本控制。 例如：

• docker/dockerfile:1 - 与最新的 1.x.x 次要 和 补丁版本保持同步。
• docker/dockerfile:1.2 - 与最新的 1.2.x 补丁版本保持同步， 并在版本 1.3.0 发布后停止接收更新。
• docker/dockerfile:1.2.1 - 不可变：从不更新。

我们推荐使用docker/dockerfile:1，它始终指向版本1语法的最新稳定版本，并在版本1发布周期内接收“次要”和“补丁”更新。BuildKit在执行构建时会自动检查语法的更新，以确保您使用的是最新版本。

如果使用特定版本，例如 1.2 或 1.2.1，则需要手动更新 Dockerfile 以继续接收错误修复和新功能。旧版本的 Dockerfile 与新版本的构建器保持兼容。

实验室频道

labs 通道提供对尚未在 stable 通道中可用的 Dockerfile 功能的早期访问。labs 镜像与稳定版本同时发布，并遵循相同的版本模式，但使用 -labs 后缀，例如：

• docker/dockerfile:labs - labs 频道上的最新版本。
• docker/dockerfile:1-labs - 与 dockerfile:1 相同，但启用了实验性功能。
• docker/dockerfile:1.2-labs - 与 dockerfile:1.2 相同，但启用了实验性功能。
• docker/dockerfile:1.2.1-labs - 不可变：从不更新。与dockerfile:1.2.1相同，但启用了实验性功能。

选择最适合您需求的渠道。如果您想利用新功能，请使用 labs 渠道。labs 渠道中的镜像包含 stable 渠道中的所有功能，另外还有早期访问功能。 labs 渠道中的稳定功能遵循 语义版本控制， 但早期访问功能不遵循，新版本可能不向后兼容。请固定版本以避免处理破坏性更改。

其他资源

有关labs功能、主构建和每日功能发布的文档，请参阅 GitHub上的BuildKit源代码仓库描述。 要查看可用镜像的完整列表，请访问 docker/dockerfileDocker Hub上的仓库， 以及Docker Hub上的 docker/dockerfile-upstream仓库 以获取开发构建。