Docker Build-Push Action v6 与下载构建产物兼容性问题解析

在 Docker 生态系统中，build-push-action 是一个广泛使用的 GitHub Action，用于构建和推送 Docker 镜像。最新发布的 v6 版本引入了一项新功能——构建摘要（build summary）记录，这项功能会在构建过程中自动上传一个 .dockerbuild 文件作为 GitHub 工作流产物（artifact）。

问题现象

当用户将 build-push-action 升级到 v6 版本后，如果在后续步骤中使用 actions/download-artifact@v4 下载所有工作流产物时，会遇到下载失败的错误提示："Unable to download artifact(s): Unable to download and extract artifact: Artifact download failed after 5 retries"。

问题根源

深入分析发现，问题的本质在于：

1. build-push-action v6 默认会上传构建记录文件（.dockerbuild），这是一个 gzip 压缩格式的文件
2. actions/download-artifact@v4 在下载所有产物时，会尝试将所有产物当作 ZIP 文件处理
3. 当遇到非 ZIP 格式的 .dockerbuild 文件时，下载过程会反复重试并最终失败

解决方案

目前有三种可行的解决方案：

方案一：完全禁用构建摘要功能

通过设置环境变量 DOCKER_BUILD_NO_SUMMARY=true 可以完全禁用构建摘要功能，这样就不会上传 .dockerbuild 文件。

方案二：仅禁用构建记录上传

从 build-push-action v6.3.0 开始，可以通过设置 DOCKER_BUILD_RECORD_UPLOAD=false 来仅禁用构建记录上传，同时保留其他摘要功能。

方案三：精确指定下载的产物名称

在使用 actions/download-artifact@v4 时，明确指定需要下载的产物名称，避免自动下载所有产物。例如：

steps:
  - uses: actions/download-artifact@v4
    with:
      name: your-specific-artifact-name

最佳实践建议

1. 如果工作流中不需要构建摘要功能，建议完全禁用以减少不必要的产物上传
2. 如果只需要部分摘要功能而不需要记录上传，使用方案二更为合适
3. 在使用下载产物功能时，尽量明确指定产物名称，避免自动下载所有产物
4. 定期检查 GitHub Action 的更新日志，了解新版本可能引入的兼容性变化

技术背景

GitHub Actions 的产物系统设计用于存储和共享工作流运行期间生成的文件。默认情况下，actions/download-artifact@v4 会尝试将所有产物当作 ZIP 文件处理，这是为了兼容大多数使用场景。然而，当遇到非 ZIP 格式的产物时，这种假设就会导致问题。

build-push-action v6 引入的构建摘要功能使用 gzip 格式存储构建记录，这是为了优化存储空间和传输效率。两种不同格式的冲突导致了兼容性问题。

未来展望

随着 GitHub Actions 生态系统的演进，预计会有更完善的机制来处理不同类型的产物格式。目前，用户需要根据实际需求选择合适的解决方案来规避兼容性问题。