使用Go语言、Moby库及BuildKit构建Docker镜像时的问题

核心问题原因 #

你遇到的错误本质是BuildKit需要活跃的会话上下文，仅设置ImageBuildOptions.Version="2"只是启用BuildKit语法，但未正确初始化BuildKit的会话环境。

关键整合步骤 #

无需完全重构现有Docker客户端，只需在现有代码基础上补充以下关键组件：

1. 初始化BuildKit会话控制器 #

在调用ImageBuild之前，创建会话管理器来管理BuildKit会话，示例代码片段：

import (
    "github.com/moby/buildkit/session"
    "github.com/moby/buildkit/session/auth/authprovider"
)

// 创建会话管理器，若需拉取私有镜像则添加认证提供者
sm := session.NewManager()
sm.Register(authprovider.NewDockerAuthProvider(yourDockerClient.Client))

2. 完善BuildKit构建选项配置 #

修改ImageBuildOptions，除设置Version=2外，需绑定会话ID与管理器：

buildOpts := types.ImageBuildOptions{
    Version:         "2",
    Tags:            []string{"your-image:tag"},
    Pull:            true,
    // 绑定会话相关配置
    SessionID:       "build-session-001", // 自定义会话标识
    SessionManager:  sm,                  // 关联会话管理器
}

3. 确保Docker守护进程启用BuildKit #

本地Docker daemon未开启BuildKit也会导致该错误，需提前配置：

• 修改/etc/docker/daemon.json添加：

  { "features": { "buildkit": true } }
  

• 重启Docker服务：systemctl restart docker（Linux）或在Docker Desktop设置中启用BuildKit

常见误区修正 #

• 无需照搬BuildKit官方示例的完整客户端实现，仅需提取会话管理和BuildKit选项配置部分整合到现有Moby客户端代码中
• 若无需私有镜像认证，可省略authprovider部分，但仍需创建空的session.Manager

内容的提问来源于stack exchange，提问作者Ferrandinand