Jenkins Pipeline中Docker Build用--secret报错的解决方案咨询

问题概述 #

执行Docker构建命令docker image build --secret id=npmrc,src=npmrc -t $IMAGE_NAME .时触发错误：unknown flag: --secret。本地Docker 25.0.3环境可正常运行该命令，但Jenkins Agent的Dockerbuild --help输出中无--secret选项，需通过该secret拉取私有GitHub npm包完成镜像构建。

原因分析 #

错误日志提示legacy builder已废弃，说明Jenkins Agent中Docker默认使用了旧版构建器，而--secret与Dockerfile中的--mount=type=secret均为BuildKit构建引擎专属特性，旧版构建器不支持这些功能。

解决方案 #

方案1：开启BuildKit构建模式 #

通过环境变量强制Docker使用BuildKit引擎，无需修改构建命令格式：

1. 在Jenkinsfile的environment块中添加BuildKit启用变量：

environment {
  DOCKER_CREDENTIALS = credentials("dockerhub")
  IMAGE_NAME = "rulerchen/tasker-3-auth"
  IMAGE_TAG = "stable-${BUILD_NUMBER}"
  DOCKER_BUILDKIT = 1 // 新增该行开启BuildKit
}

2. 保持原构建命令不变，此时Docker会自动使用BuildKit引擎执行构建。

方案2：改用docker buildx build命令（推荐） #

由于旧版构建器即将被移除，官方推荐使用buildx命令构建镜像，需确保Jenkins Agent已安装buildx组件：

1. 安装buildx组件：
   在Jenkins Agent上创建~/.docker/cli-plugins目录，下载对应Agent架构的buildx二进制文件到该目录，赋予文件可执行权限。可在Pipeline的Prepare Environment阶段添加以下shell步骤完成安装：

stage("Prepare Environment") {
  steps {
    withCredentials([string(credentialsId: 'NPM_TOKEN', variable: 'NPM_TOKEN')]) {
      git branch: 'main', credentialsId: 'github', url: 'https://github.com/RulerChen/tasker-auth'
      // 安装buildx
      sh 'mkdir -p ~/.docker/cli-plugins'
      // 替换为对应架构的buildx二进制文件下载命令
      sh 'curl -SL <对应架构的buildx二进制文件地址> -o ~/.docker/cli-plugins/docker-buildx'
      sh 'chmod +x ~/.docker/cli-plugins/docker-buildx'
      sh 'npm install'
    }
  }
}

2. 修改构建命令，添加--load参数（将构建结果加载到本地镜像仓库，否则后续tag/push会找不到镜像）：

stage("Build and Push") {
  steps {
    sh 'docker login -u $DOCKER_CREDENTIALS_USR --password $DOCKER_CREDENTIALS_PSW'
    sh "docker buildx build --secret id=npmrc,src=npmrc -t $IMAGE_NAME --load ." // 修改为buildx命令
    sh "docker tag $IMAGE_NAME $IMAGE_NAME:$IMAGE_TAG"
    sh "docker tag $IMAGE_NAME $IMAGE_NAME:stable"
    sh "docker push $IMAGE_NAME:$IMAGE_TAG"
    sh "docker push $IMAGE_NAME:stable"
  }
}

额外检查 #

• 确认Jenkins Agent的Docker版本不低于20.10（BuildKit在该版本后默认集成），若版本过低需升级Agent中的Docker。
• 确保Jenkins Agent以root权限运行（已在docker-compose配置中设置user: root，满足要求）。

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