GitHub Actions执行Docker构建报错：'docker buildx build'需1个参数

针对你遇到的ERROR: "docker buildx build" requires exactly 1 argument报错，以下是具体的排查和解决步骤：

1. 检查命令参数格式 #

最常见的原因是docker buildx build命令的参数拆分错误，尤其是多行书写时的换行问题。比如错误写法：

run: |
  docker buildx build \
    --tag username/image:latest \
    --push
    .

这里的.被拆成了单独的命令，导致buildx build缺少上下文参数。正确写法需要在每行末尾保留反斜杠，包括上下文路径所在行的上一行：

run: |
  docker buildx build \
    --tag username/image:latest \
    --push \
    .

2. 确保代码已拉取到Runner #

如果没有执行代码checkout步骤，Runner的工作目录是空的，即使写了.作为上下文，也会因为没有文件导致命令异常。必须添加：

- name: Checkout code
  uses: actions/checkout@v4

3. 初始化Docker Buildx环境 #

GitHub Actions的默认Runner环境可能没有正确配置Buildx，需要显式初始化：

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

4. 验证变量/密钥配置 #

如果使用环境变量或GitHub Secrets定义镜像标签，要确保变量已正确设置且不为空。比如：

run: |
  docker buildx build \
    --tag ${{ secrets.DOCKERHUB_USERNAME }}/my-app:${{ github.sha }} \
    --push \
    .

需确认DOCKERHUB_USERNAME已在仓库Secrets中配置，github.sha是GitHub内置变量无需额外设置。

完整工作流示例 #

参考以下正确的工作流配置，对比你的文件排查差异：

name: Push Docker Image to DockerHub
on:
  push:
    branches: [ main ]

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Log in to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        run: |
          docker buildx build \
            --tag ${{ secrets.DOCKERHUB_USERNAME }}/my-app:latest \
            --tag ${{ secrets.DOCKERHUB_USERNAME }}/my-app:${{ github.sha }} \
            --push \
            .

这个报错和GitHub的全局设置无关，基本都是工作流命令格式或步骤缺失导致的，按上面的步骤逐一排查即可解决。

内容的提问来源于stack exchange，提问作者Даниил