Docker Compose使用${TAG:-latest}时为何拉取不存在的镜像标签

报错里的v1.15.0-22-gba57975是标准的git describe命令输出，格式为「最近的Git标签-标签之后的提交次数-g当前提交短哈希」，这个值被注入到了TAG环境变量里。docker-compose的变量插值优先级为：命令行传入变量 > 当前shell环境变量 > 工作目录.env文件 > compose文件内配置的默认值，只要TAG在前面几个优先级环节被赋值，你写的${TAG:-latest}里的latest默认值根本不会生效。

常见的隐式赋值来源有两个：

• 当前shell会话残留：该项目自带的构建脚本、Makefile中默认写了export TAG=$(git describe)逻辑，只要你之前在当前终端窗口跑过项目本地构建、镜像打包相关命令，这个变量就会残留在当前shell会话中，后续执行docker-compose命令时会被优先读取。
• .env加载路径错误：使用-f tools/docker-compose.yml指定compose文件路径时，docker-compose默认只会加载执行命令时所在工作目录下的.env文件，不会自动读取tools目录下的.env配置。如果你在项目根目录执行命令，哪怕tools目录下的.env没配置TAG，只要根目录下有其他.env文件定义了TAG，一样会被加载生效。

额外说明：Helm部署使用的values.yaml属于K8s部署配置体系，和docker-compose是完全独立的两套配置逻辑，二者配置的镜像标签不一致属于正常情况，不会互相干扰。

1. 先确认当前shell是否存在残留的TAG变量，执行：

echo $TAG

如果输出值就是报错的v1.15.0-22-gba57975，即可直接定位为环境变量残留导致的问题。

2. 可直接查看compose完成变量渲染后的最终配置，确认镜像的实际取值，无需反复猜测变量来源：

docker-compose -p anonlink -f tools/docker-compose.yml config

输出结果中找到db_init服务的image字段，显示的标签就是compose实际会拉取的标签。

3. 按需选择对应修复方案即可：

• 临时启动可直接清除残留变量，执行时会自动使用compose配置的默认latest标签：

unset TAG && docker-compose -p anonlink -f tools/docker-compose.yml up --remove-orphans

• 要拉取已确认存在的稳定版本，直接在命令前显式传入TAG，跳过所有隐式赋值干扰：

TAG=v1.15.0 docker-compose -p anonlink -f tools/docker-compose.yml up --remove-orphans

• 需要长期固定版本时，在你日常执行docker-compose命令的当前工作目录下新建.env文件，写入TAG=v1.15.0，后续启动时compose会自动读取该配置，不会被其他隐式变量覆盖。

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