执行 docker run、docker pull 或 docker build 时出现 invalid reference format，表示Docker在真正拉取镜像之前，已经无法把输入解析成合法的镜像引用。这不是仓库中没有该镜像，也不是Registry网络超时。
Docker官方给出的镜像引用结构为 [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]。实际报错经常由大写仓库名、空变量、错误冒号或Shell换行引起。
先把最终传给Docker的值打印出来
脚本中的变量可能为空、带空格或包含不可见换行。不要只看脚本源代码，应查看展开后的实际值：
printf ‘IMAGE=<%s>\n’ “$IMAGE” printf ‘%q\n’ “$IMAGE” set -x docker pull “$IMAGE” set +x
尖括号之间为空，或值被拆成多个参数时，先修复变量来源。 不要删除双引号来碰运气，未引用变量反而会让空格和通配符继续改变参数。
核对镜像引用的基本结构
常见有效写法包括：
nginx nginx:1.28 library/nginx:1.28 registry.example.com/team/app:v2 registry.example.com:5000/team/app:v2
仓库路径应使用小写名称，Registry端口位于主机名后的冒号中，标签位于最后一个仓库名后的冒号中。镜像标签与主机端口都使用冒号，但位置和含义不同，不能随意交换。
大写字母和多余分隔符最常见
下面这些输入容易触发解析错误：
MyTeam/App:latest registry.example.com//team/app:v2 registry.example.com/team/app: registry.example.com:5000:team/app
可先把仓库名转换为统一的小写命名，并分别保存仓库与标签：
REPO=’registry.example.com/team/app’ TAG=’v2′ IMAGE=”${REPO}:${TAG}” docker image pull “$IMAGE”
不要对整个引用盲目执行小写转换。 标签虽然可以包含更多字符，但团队最好采用稳定、可预测的命名规则。
检查Shell换行和反斜杠后空格
多行命令中的反斜杠必须是该行最后一个字符。反斜杠后多了空格，Shell不会按预期续行，下一行参数可能被当作新命令或位置参数：
docker run –rm \ –name web \ nginx:1.28
复杂命令可以先整理成数组，避免字符串拼接：
args=(–rm –name web -p 8080:80) docker run “${args[@]}” nginx:1.28
看到错误位置指向某个参数时，也要检查它前一行的续行符。 Docker可能把本应属于选项的值误认为镜像名称。
Compose和CI要查看渲染结果
Compose文件里的镜像名经常由环境变量拼接。先查看解析后的配置：
docker compose config docker compose config –images
CI中则应在不泄露凭据的前提下检查仓库、镜像名和标签是否为空。推荐为必填变量添加Shell校验：
: “${IMAGE_REPO:?IMAGE_REPO is required}” : “${IMAGE_TAG:?IMAGE_TAG is required}” IMAGE=”${IMAGE_REPO}:${IMAGE_TAG}”
不要把Registry密码或完整认证变量输出到日志。 镜像引用可以打印，登录凭据必须继续脱敏。
不要用latest掩盖标签生成错误
变量生成失败时临时删掉标签，Docker可能默认使用 latest，但这会把格式问题变成版本漂移问题。生产部署应明确镜像标签，重要环境还可记录镜像摘要。
需要复现Compose和CI镜像命名流程时，可在 萤光云 准备测试机，或通过 LightNode 按小时搭建临时Runner。验证通过后应把命名校验写进流水线，而不是依赖人工记忆。
修正后如何验收
先单独验证引用可解析和可拉取，再运行完整部署：
docker image pull “$IMAGE” docker image inspect “$IMAGE” –format ‘{{.Id}}’ docker run –rm “$IMAGE” –version
最后一条命令是否适用取决于镜像入口程序，可替换为项目的健康检查。验收标准是同一引用在本地、Compose和CI中解析一致，并指向预期的仓库与版本。
FAQ
invalid reference format和manifest unknown一样吗？
不一样。前者通常在本地解析引用时发生；后者通常表示引用格式已通过，但Registry中找不到对应清单。
镜像仓库名可以包含大写字母吗？
Docker镜像仓库路径应使用小写命名。建议从项目创建时就统一小写，避免不同脚本产生不一致引用。
为什么手动执行成功，脚本里却失败？
通常是脚本变量为空、包含隐藏字符，或多行命令的反斜杠后带空格。打印转义后的最终值最容易发现差异。
温馨提示
先还原Docker实际收到的完整镜像引用，再修改命令。 随意删除标签、引号或仓库前缀可能暂时绕过报错，却会让部署拉到错误版本。
