Docker Compose本地缓存导出失败：GitLab流水线环境排查

1. 强制Docker Compose使用指定的Buildx Builder #

GitLab流水线的每个job步骤是独立shell环境，docker buildx create --use的生效范围仅限当前shell，后续步骤不会自动继承。解决方式有两种：

方式一：在compose命令中指定builder #

执行build命令时显式指定创建好的builder：

docker compose --builder multiarch-builder build

方式二：在docker-compose.yml中配置默认builder #

在services同级添加全局builder配置，让服务统一使用指定的builder：

name: "dev"
x-build-config: &build-config
  builder: multiarch-builder
services:
  my-service:
    build:
      <<: *build-config
      context: .
      target: development
      dockerfile: Dockerfile
      cache_from:
        - type=local,src=./.docker-cache/
      cache_to:
        - type=local,dest=./.docker-cache/,mode=max

2. 确保GitLab Runner配置满足要求 #

如果你的GitLab Runner使用docker executor，需要：

• 开启privileged模式：在runner的config.toml中设置privileged = true，docker-container驱动需要访问Docker daemon的特权权限才能正常工作。
• 配置目录缓存：在.gitlab-ci.yml中将.docker-cache加入缓存路径，避免每次job重新构建缓存：

  cache:
    paths:
      - .docker-cache/
  

3. 显式激活Buildx Builder #

在执行docker compose build前，先确认并激活目标builder：

docker buildx use multiarch-builder
docker compose build

4. 验证Docker版本兼容性 #

确保GitLab Runner环境中的工具版本足够新：

• Docker Compose ≥ v2.10.0
• Buildx ≥ v0.9.0
  可在流水线步骤中添加版本检查：

docker compose version
docker buildx version

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