Docker Build-Push Action 中工作目录与构建上下文的常见误区解析

在使用 GitHub Actions 的 docker/build-push-action 进行容器镜像构建时，开发者经常会遇到一个典型问题：明明在文件系统中能看到 Dockerfile，但构建时却报错"no such file or directory"。这种情况在项目采用 monorepo 结构时尤为常见。

问题本质分析

问题的根源在于对 GitHub Actions 中工作目录(defaults.run.working-directory)与 Docker 构建上下文(context)的概念理解不够清晰。虽然两者都涉及路径设置，但作用范围和层级完全不同：

1. 工作目录设置：仅影响当前 job 中的 run 命令执行路径
2. 构建上下文：决定 Docker 构建时能够访问的文件范围

典型错误配置

开发者常犯的错误是在 monorepo 项目中这样配置：

defaults:
  run:
    working-directory: subdirectoryA

steps:
  - uses: docker/build-push-action@v5
    with:
      context: .
      push: true

这种配置会导致：

• Maven 构建等 run 命令确实在 subdirectoryA 下执行
• 但 Docker 构建仍以仓库根目录为上下文
• 最终因找不到 Dockerfile 而失败

正确解决方案

针对 monorepo 项目，推荐以下两种正确配置方式：

方案一：调整构建上下文路径

steps:
  - uses: docker/build-push-action@v5
    with:
      context: subdirectoryA
      push: true

方案二：使用 Git 路径语法

steps:
  - uses: docker/build-push-action@v5
    with:
      context: .
      file: subdirectoryA/Dockerfile
      push: true

技术原理深入

理解这个问题的关键在于掌握三个核心概念：

1. GitHub Actions 工作目录：通过 defaults.run.working-directory 设置，仅影响 run 步骤的当前工作目录，对 uses 步骤无效

2. Docker 构建上下文：决定哪些文件可以用于 COPY/ADD 等指令，必须包含 Dockerfile 及其引用的所有文件

3. Buildx 的工作机制：在容器内执行构建，需要正确映射宿主机文件路径

最佳实践建议

1. 对于复杂项目结构，建议显式指定 context 和 file 参数
2. 在调试阶段可以添加 ls 步骤验证文件路径
3. 考虑使用相对路径时从仓库根目录开始计算
4. 对于多模块项目，可以为每个子模块创建独立的工作流文件

通过正确理解这些概念和配置方式，开发者可以避免常见的路径问题，实现高效的容器化构建流程。