Docker BuildKit问题：等待本地基础镜像构建完成

项目背景与问题 #

项目结构如下：

./docker/Base/Dockerfile
./docker/ServiceA/Dockerfile
./docker/ServiceB/Dockerfile
./docker-compose.yml

ServiceA和ServiceB共享本地构建的基础镜像servicebase，基础镜像的Dockerfile内容：

FROM python:3.10-slim
# 执行通用依赖安装等操作
CMD tail -f /dev/null

ServiceA和ServiceB的Dockerfile以该基础镜像为起点：

# ServiceA的Dockerfile
FROM servicebase:latest
# 执行ServiceA专属配置
CMD /foo/serviceA

# ServiceB的Dockerfile
FROM servicebase:latest
# 执行ServiceB专属配置
CMD /foo/serviceB

对应的docker-compose.yml配置：

version: '3.8'

services:
  servicebase:
    image: servicebase
    build:
      context: .
      dockerfile: docker/Base/Dockerfile
    container_name: servicebase
  serviceA:
    depends_on:
      - servicebase
    build:
      context: .
      dockerfile: docker/ServiceA/Dockerfile
  serviceB:
    depends_on:
      - servicebase
    build:
      context: .
      dockerfile: docker/ServiceB/Dockerfile

运行docker compose up时遇到问题：Docker BuildKit会并行构建所有镜像，导致ServiceA/B构建时servicebase镜像尚未生成，进而尝试从DockerHub拉取该镜像失败，报错：

Status: pull access denied for servicebase, repository does not
exist or may require 'docker login': denied: requested access to the
resource is denied, Code: 1

禁用BuildKit（执行export DOCKER_BUILDKIT=0）后，构建改为串行可正常运行，但用户不想依赖禁用BuildKit的方式，也不想将servicebase推送到DockerHub，询问当前设计是否存在根本性缺陷，或是否有BuildKit配置选项可解决该问题。

解决方案 #

1. 当前设计的核心问题 #

depends_on在docker-compose中仅控制容器启动顺序，完全不控制镜像构建顺序。即使给ServiceA/B添加了对servicebase服务的依赖，BuildKit依然会并行触发所有镜像的构建任务，因为它默认不会关联服务间的构建依赖逻辑。

2. 无需禁用BuildKit的解决方法 #

方法一：显式控制镜像构建顺序（推荐）

不需要在docker-compose中为基础镜像创建服务，先单独构建基础镜像，再启动服务：

# 先构建本地基础镜像
docker build -t servicebase -f docker/Base/Dockerfile .
# 再启动ServiceA/B，此时会直接使用本地已存在的servicebase镜像
docker compose up --build

或者通过docker-compose的构建命令分步执行：

docker compose build servicebase
docker compose up --build

方法二：调整Dockerfile为多阶段构建

将基础镜像的构建逻辑整合到ServiceA/B的Dockerfile中，利用BuildKit的缓存机制避免重复构建：

# ServiceA的Dockerfile
# 第一阶段：构建基础镜像层（BuildKit会自动复用缓存）
FROM python:3.10-slim AS servicebase
# 执行通用依赖安装等操作

# 第二阶段：构建ServiceA专属镜像
FROM servicebase
# 执行ServiceA专属配置
CMD /foo/serviceA

ServiceB的Dockerfile做同样调整即可。这种方式不需要单独维护基础镜像的构建流程，BuildKit会自动识别并复用基础层的缓存，避免重复执行通用依赖安装步骤。

方法三：利用BuildKit的缓存源配置

在docker-compose.yml中为ServiceA/B的构建指定cache_from，让其优先使用本地已构建的servicebase镜像作为缓存：

version: '3.8'

services:
  servicebase:
    image: servicebase
    build:
      context: .
      dockerfile: docker/Base/Dockerfile
  serviceA:
    build:
      context: .
      dockerfile: docker/ServiceA/Dockerfile
      cache_from:
        - servicebase:latest
      args:
        - BUILDKIT_INLINE_CACHE=1
    depends_on:
      - servicebase
  serviceB:
    build:
      context: .
      dockerfile: docker/ServiceB/Dockerfile
      cache_from:
        - servicebase:latest
      args:
        - BUILDKIT_INLINE_CACHE=1
    depends_on:
      - servicebase

注意：这种方式仍需要确保servicebase镜像先完成构建，可配合分步构建命令使用。

3. 总结 #

当前设计的核心问题是混淆了服务启动依赖和镜像构建依赖，depends_on无法控制BuildKit的并行构建行为。无需禁用BuildKit，推荐优先选择「显式控制构建顺序」或「多阶段构建」的方案，既不需要推送镜像到DockerHub，也能保证构建流程的稳定性。

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