Bitbucket流水线推送Docker Hub镜像失败：标签不存在问题排查

报错原因分析 #

出现“标签不存在”的核心原因是Docker镜像未成功构建，导致推送时指定的标签未被创建，具体触发场景包括：

1. 变量拼接异常
   deploy.sh中COMMIT=${BITBUCKET_COMMIT}-${2}的拼接逻辑存在漏洞：如果BITBUCKET_COMMIT在deploy步骤中未被正确注入（或为空），会生成类似-202405201234的无效标签，Docker构建时会因为标签格式非法失败，最终推送时提示标签不存在。

2. 未检查构建结果
   deploy.sh中docker build执行后未做错误校验，即使构建过程中出现依赖下载失败、Dockerfile语法错误等问题，脚本仍会继续执行docker push，此时目标标签根本不存在，直接触发报错。

3. 分支逻辑冲突（非核心，但需注意）
   build-docker.sh中仅当分支为指定分支时才执行推送，但deploy.sh中无分支判断，若在非目标分支误触发deploy步骤，可能因权限或镜像命名问题导致构建失败。

修复方案 #

1. 修复变量拼接逻辑 #

修改deploy.sh中的COMMIT变量定义，确保变量为空时仍生成合法标签：

#!/usr/bin/env bash

ENV=${1}
# 给BITBUCKET_COMMIT设置默认值，避免空值导致标签格式非法
COMMIT="${BITBUCKET_COMMIT:-unknown}-${2}"

# Build Docker image and push to repository
docker login -u ${DOCKER_USER} -p ${DOCKER_PASSWORD}
docker build -t intraedge/truyo-php:${ENV}-${COMMIT} -t intraedge/truyo-php:${ENV} --build-arg env=${ENV} .
docker push intraedge/truyo-php:${ENV}
docker push intraedge/truyo-php:${ENV}-${COMMIT}

2. 添加构建结果校验 #

在docker build后加入退出码检查，确保构建成功再执行推送：

docker build -t intraedge/truyo-php:${ENV}-${COMMIT} -t intraedge/truyo-php:${ENV} --build-arg env=${ENV} .
# 检查构建是否成功，失败则终止脚本
if [ $? -ne 0 ]; then
    echo "Docker镜像构建失败，终止推送"
    exit 1
fi

3. 验证变量有效性 #

在deploy.sh开头添加变量打印，方便排查变量注入问题：

#!/usr/bin/env bash

ENV=${1}
COMMIT="${BITBUCKET_COMMIT:-unknown}-${2}"

# 打印变量值，排查是否为空或格式异常
echo "当前环境：${ENV}"
echo "提交哈希：${BITBUCKET_COMMIT}"
echo "时间标签：${2}"
echo "最终镜像标签：intraedge/truyo-php:${ENV}-${COMMIT}"

# Build Docker image and push to repository
docker login -u ${DOCKER_USER} -p ${DOCKER_PASSWORD}
docker build -t intraedge/truyo-php:${ENV}-${COMMIT} -t intraedge/truyo-php:${ENV} --build-arg env=${ENV} .
if [ $? -ne 0 ]; then
    echo "Docker镜像构建失败，终止推送"
    exit 1
fi
docker push intraedge/truyo-php:${ENV}
docker push intraedge/truyo-php:${ENV}-${COMMIT}

4. 统一标签命名规范（可选优化） #

将build-docker.sh和deploy.sh的标签格式统一，避免混淆。例如在deploy.sh中使用与build-docker.sh一致的${ENVIRONMENT}-${BITBUCKET_COMMIT}基础标签，再追加时间戳：

COMMIT="${BITBUCKET_COMMIT:-unknown}-${2}"

内容的提问来源于stack exchange，提问作者P Nisanth Reddy