构建并推送Docker镜像至Docker Hub时遭遇未授权问题

1. 核对GitHub Secrets配置 #

• 登录GitHub仓库，进入「Settings > Secrets and variables > Actions」，确认已添加DOCKER_HUB_USERNAME和DOCKER_HUB_TOKEN两个密钥
• 确保密钥名称与Workflow文件中引用的完全一致（大小写敏感）
• 注意：如果Docker Hub账号开启了两步验证，必须使用个人访问令牌作为DOCKER_HUB_TOKEN，不能用账号密码

2. 检查Workflow登录步骤的语法 #

• 确保登录步骤的写法符合官方规范，示例：

- name: Log in to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKER_HUB_USERNAME }}
    password: ${{ secrets.DOCKER_HUB_TOKEN }}

• 禁止硬编码用户名或密码，必须通过${{ secrets.XXX }}引用密钥
• 检查参数拼写，比如不要把password误写为passwd

3. 验证Docker Hub令牌权限 #

• 登录Docker Hub，进入「Account Settings > Security > Access Tokens」
• 确认创建的令牌拥有write权限（推送镜像必须具备该权限），若权限不足需重新生成令牌并更新GitHub Secrets
• 检查令牌是否过期，过期的令牌会直接导致未授权错误

4. 排查网络与环境问题 #

• 如果GitHub Runner处于受限网络环境，可能无法正常连接Docker Hub，可添加测试步骤验证：

- name: Test Docker Hub connectivity
  run: curl https://hub.docker.com/v2/users/

• 若连接失败，需配置Runner的代理或调整网络策略

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