使用docker/build-push-action@v3时嵌套隐藏文件夹未被复制的问题

核心原因：BuildKit 与传统 Docker 构建的上下文过滤差异 #

你遇到的问题本质是 docker/build-push-action@v3 默认启用 BuildKit 构建，而 BuildKit 和传统 Docker 构建在处理构建上下文时的规则不同：

• 本地执行 docker build 时，大概率用的是传统构建模式，不会读取 .gitignore 文件过滤上下文内容，所以 next/.next 能被正常复制。
• 而 BuildKit 会自动读取构建上下文目录中的 .gitignore，如果其中包含了 .next（这是 Next.js 项目常见的配置），即使该文件夹在 Runner 上实际存在，BuildKit 也会将其排除在构建上下文之外，导致 Dockerfile 的 COPY 步骤找不到它。

解决方案 #

1. 用 .dockerignore 强制包含 .next 文件夹

在 Dockerfile 所在的构建上下文目录中，创建或修改 .dockerignore 文件，明确指定要包含 next/.next：

# 如果.gitignore里排除了.next，这里强制包含
!next/.next

如果你的 .dockerignore 有全局排除规则（比如 *），需要先取消对 next 目录的排除，再包含 .next：

!next/
!next/.next

这样 BuildKit 就会把 next/.next 纳入构建上下文，COPY 步骤就能正常复制该文件夹。

2. 确认构建上下文路径配置正确

检查 docker/build-push-action 的 context 参数是否指向了包含 next 文件夹的正确目录（通常是当前目录 .）：

- name: Build and push image
  uses: docker/build-push-action@v3
  with:
    context: .  # 确保这里是正确的上下文路径
    push: true
    tags: ${{ steps.auth.outputs.registry }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

可以在构建前添加一个验证步骤，确认目录结构：

- name: Check build context contents
  run: ls -la next/

3. 排查权限或目录结构问题

虽然你用 tmate 确认了 .next 存在，但仍有可能出现权限不足的情况。可以在下载工件后添加步骤修复权限：

- name: Fix directory permissions
  run: chmod -R 755 next/

内容的提问来源于stack exchange，提问作者sc-leeds