buildctl

直接调用 BuildKit 构建镜像

补充说明

buildctl 是 BuildKit 的客户端，直接和 buildkitd 通信，适合没有 Docker 的环境、CI 和自定义构建流程。它比 docker build 更底层，输出和缓存都要显式配置。

常用示例

buildctl --addr unix:///run/buildkit/buildkitd.sock debug workers
buildctl build \
  --frontend dockerfile.v0 \
  --local context=. \
  --local dockerfile=. \
  --output type=docker,name=app:latest
buildctl build \
  --frontend dockerfile.v0 \
  --local context=. \
  --local dockerfile=. \
  --output type=image,name=registry.example.com/app:1.0,push=true
buildctl build \
  --frontend dockerfile.v0 \
  --local context=. \
  --local dockerfile=. \
  --output type=oci,dest=app.tar
buildctl du
buildctl prune

易错点与排错

• buildctl 只是客户端；必须先运行 buildkitd，并确认 socket 地址。
• --local 的路径是客户端提供的上下文；多个 local 名称要和 frontend 对应。
• type=docker 只适合单平台；多平台和 OCI 输出用 type=image 或 type=oci。
• push=true 需要 registry 认证；凭据通过 --opt 或 Docker 配置传入。
• 缓存默认在 buildkitd 本地；跨机器复用要显式导出/导入 registry 缓存。
• rootless 模式对网络和挂载有限制；构建失败先看 daemon 日志。
• prune 会删除缓存，影响后续构建速度；确认磁盘和缓存策略。
• 不安全 registry 需要 daemon 配置；客户端单方面加参数不会生效。

相关命令

• docker-buildx — BuildKit 的 Docker 封装
• docker — 容器运行时
• crane — 镜像检查与搬运