Docker Build-Push-Action 中解决 GitHub 缓存构建失败问题

在使用 Docker 的 build-push-action 进行容器镜像构建时，许多开发者会选择启用 GitHub 缓存（GH Cache）来加速构建过程。然而，在实际应用中可能会遇到缓存导出失败的问题，本文将深入分析这一常见问题的根源及解决方案。

问题现象

当开发者配置了以下工作流时：

1. 使用 setup-buildx-action 设置构建器，指定 docker-container 驱动
2. 启用 GitHub 缓存功能（cache-from 和 cache-to 参数）
3. 进行容器镜像构建

系统会报错："Cache export is not supported for the docker driver"，提示需要切换驱动或启用 containerd 镜像存储。检查构建器信息时发现，尽管配置了 docker-container 驱动，实际仍然使用默认的 docker 驱动。

根本原因分析

经过深入排查，发现问题源于工作流中 Azure/docker-login@v2 动作的影响。该动作在执行时会覆盖 DOCKER_CONFIG 环境变量，导致以下连锁反应：

1. 之前通过 setup-buildx-action 创建的构建器配置丢失
2. 系统回退到默认的 docker 驱动
3. GitHub 缓存功能因驱动不兼容而失败

解决方案

针对这一问题，我们提供两种可靠的解决方案：

方案一：调整动作执行顺序

将构建器设置步骤（Docker Setup Buildx）移到 Azure 登录步骤（Azure Container Registry Login）之后执行。这样可以确保：

• 构建器配置不会被后续登录动作覆盖
• 保持原有的缓存功能配置

方案二：替换登录动作

推荐使用官方的 docker/login-action 替代 Azure/docker-login@v2，具体配置如下：

- name: Login to ACR
  uses: docker/login-action@v3
  with:
    registry: 你的ACR登录服务器
    username: 你的用户名密钥
    password: 你的密码密钥

这一方案的优势在于：

• 官方维护的动作不会干扰 DOCKER_CONFIG 环境变量
• 与 build-push-action 有更好的兼容性
• 保持构建器配置的完整性

最佳实践建议

1. 在执行涉及多步骤的 CI/CD 流程时，应注意各动作之间的相互影响
2. 优先选择同一生态系统的工具链（如都使用 Docker 官方动作）
3. 在复杂工作流中，建议通过输出日志验证各步骤的实际效果
4. 对于缓存等高级功能，确保构建器配置正确且未被后续步骤覆盖

通过以上分析和解决方案，开发者可以顺利地在 Docker build-push-action 中启用 GitHub 缓存功能，显著提升容器镜像的构建效率。