GitHub Action构建推送Docker镜像失败：无效标签格式排查

错误原因分析 #

报错invalid tag "***/e2bdy:"说明镜像标签格式不合法，核心问题是标签末尾仅带冒号却未指定版本号（如latest），或者变量未正确解析导致标签结构缺失。

具体排查与解决步骤 #

• 确认Secrets配置有效性
  如果使用${{ secrets.DOCKER_USERNAME }}，先在GitHub仓库的「Settings > Secrets and variables > Actions」里检查DOCKER_USERNAME是否已正确设置且值不为空。可在action中临时添加验证步骤（公开仓库请勿输出敏感内容）：

  - name: 验证Docker用户名变量
    run: echo "用户名变量值：${{ secrets.DOCKER_USERNAME }}"
  

• 检查镜像标签格式
  确保标签严格遵循用户名/镜像名:版本号的格式，比如musnow/e2bdy:latest，禁止出现用户名/镜像名:这种末尾带冒号但无版本号的写法。

• 核对buildx构建命令
  确保docker/build-push-action的tags参数格式正确，无语法错误。示例正确配置：

  - name: 构建并推送镜像
    uses: docker/build-push-action@v5
    with:
      context: .
      push: true
      tags: ${{ secrets.DOCKER_USERNAME }}/e2bdy:latest
  

• 排查拼写与特殊字符
  替换为实际用户名后仍失败时，检查用户名、镜像名是否有拼写错误，是否包含空格或Docker不允许的特殊字符（需注意Docker Hub的命名规则，比如部分特殊字符不支持）。

• 验证Action环境兼容性
  确保使用的Docker相关Action是最新版本，比如docker/setup-buildx-action@v3、docker/login-action@v3，避免旧版本的兼容性问题。

完整示例Action配置 #

name: 构建并推送Docker镜像

on:
  push:
    branches: [ main ]

jobs:
  build-image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 初始化Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: 登录Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: 构建并推送
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ secrets.DOCKER_USERNAME }}/e2bdy:latest

内容的提问来源于stack exchange，提问作者musnow