镜像名解析失败
invalid reference format 表示镜像名解析失败：命名里含非法字符、变量为空导致参数后缺值、参数顺序写错，或把宿主路径的写法混进了镜像名。
基本信息
| 报错 | invalid reference format |
|---|---|
| 高频触发 | 脚本变量为空、名字含空格或大写字符 |
| 命名规范 | 仓库、命名空间、名称与标签均为小写 |
| 允许字符 | 小写字母数字以及点、下划线、短横线、斜杠与冒号 |
| 排查手法 | 打印展开后的真实命令 |
典型使用场景
- CI 里变量未注入导致镜像名不完整
- 本地构建时把宿主路径当镜像名传入
- 排查脚本拼接镜像名时的转义问题
- 核对镜像名是否符合命名规范
- 引用镜像时报格式错误时定位
定位与规避
定位与规避
TAG=1.0; docker build -t app/web:$TAG . # 变量为空时标签会缺失
echo "docker build -t app/web:$TAG ." # 打印真实命令核对
docker pull ${IMAGE:-app/web:1.0} # 提供默认值避免空值
docker images | head -5 # 核对本地镜像命名线索与处理方向
| 线索 | 原因 | 处理方向 |
|---|---|---|
| 报错里冒号后为空 | 变量未注入 | 给变量加默认值或校验 |
| 名字含大写字符 | 不符合命名规范 | 统一改为小写 |
| 出现反斜杠 | 把宿主路径当镜像名 | 改用正确的镜像名 |
| 参数顺序异常 | 选项与位置参数写错 | 按语法调整顺序 |
镜像名规范：小写字母数字与点、下划线、短横线、斜杠与冒号，别混入空格与反斜杠。
CI 变量未注入时标签为空，错误信息里只显示冒号后的空值，容易看漏。
把宿主路径当成镜像名传给构建命令也会触发同类错误。
排查时先打印展开后的真实命令，比反复看报错文字更快定位。
给变量加默认值是不错的防护手段，能避免空值直接拼进命令。
团队里统一镜像命名规范，能减少这类拼写层面的问题。
构建与推送用的镜像名要保持一致，否则会出现本地有镜像、而推送目标却写成另一个名字的情况，排查时先对齐两处命名。