快速修复
# 一键：先看 docker 实际收到的镜像名，再用一个必然能过语法校验的命令对照
echo "$IMAGE"
docker run ubuntu echo hi # 全小写、无空格、无引号残留
你会遇到什么
docker run / docker pull 一执行就报 docker: invalid reference format: repository name (library/Ubuntu) must be lowercase，或只给一句干巴巴的 docker: invalid reference format。镜像明明存在、网络也通，就是起不来。
命令里某个字符不合 Docker 的镜像名规则——最常见是镜像仓库名大写、引号里带空格、变量没展开（PowerShell 里 ${pwd} 之类）。
本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。
为什么会这样
Docker 镜像引用（image reference）有严格语法：[仓库/]名称[:标签]。仓库名只允许小写字母、数字和 -_.，标签允许字母数字 _ - .。任何一个字符越界，daemon 直接拒绝解析，报 invalid reference format。常见翻车点：
| 翻车点 | 例子 | 报错 |
|---|---|---|
| 仓库名大写 | docker run Ubuntu | invalid reference format: repository name (library/Ubuntu) must be lowercase |
| 值里带空格 | docker run "ubuntu "（引号里混进空格） | invalid reference format（短句） |
| 变量没展开 | PowerShell ${pwd} / 脚本里 ${TAG} 未定义 | invalid reference format（展开后是空/非法字符） |
docker CLI 收到 docker run <image> 后，先把 <image> 按 reference 语法解析成「仓库 + 标签 + digest」三元组，再决定去哪拉。解析失败发生在任何网络请求之前——所以这条报错永远来自 CLI 本地校验，跟 daemon、镜像源、网络都没关系。它长得像网络问题，其实是纯字符串问题。
确定性推论：报错时先把命令里最终拼出来的镜像名用 echo 打出来看，空格/大小写/未展开变量一眼可见；校验规则只有一条：仓库名全小写、无空格。
一步步来
1. 打印最终镜像名 — 必做
# 报错的是哪条命令，就把它的镜像名部分 echo 出来
echo "ubuntu " # 你会看到尾部空格
echo "$TAG" # 变量是否为空 / 含非法字符
2. 按报错形态分流 — 按诊断结果
- 报错带
repository name (library/Ubuntu) must be lowercase→ 仓库名有大写：改成全小写（Ubuntu→ubuntu）。 - 报错只有
invalid reference format→ 多半是空格或空字符串：去掉引号内多余空格，或变量先echo确认展开结果。 - 变量场景：PowerShell 里
${pwd}是「当前路径字符串」，不是$(pwd)的执行结果——用$(pwd)（PowerShell）或${PWD}（bash），或先展开成变量再拼。
3. 用最简命令确认语法 — 必做
docker run alpine echo ok # 全小写 + 无空格，能跑通 = 你原命令的字符串有问题
怎么确认修好了
docker run alpine echo ok 输出 ok 且没有 invalid reference format；修正后的原命令能正常拉取/启动。
其它环境的表现
| 环境 | 说明 |
|---|---|
| 仓库名大写 | library/Ubuntu 完整报错（实测） |
| 值里带空格 | 短句 docker: invalid reference format（实测） |
| digest 引用 | image@sha256:... 的 digest 格式不对同样报 invalid reference format |
症状
# 形态 1：仓库名大写（完整文案）
docker: invalid reference format: repository name (library/Ubuntu) must be lowercase
# 形态 2：字符串里有空格（短句）
docker: invalid reference format
Run 'docker run --help' for more information特征：docker run / docker pull 立即失败，exit 125，不经过网络；命令字符串里有大写/空格/未展开变量。
原因
镜像引用有严格语法：仓库名只允许小写字母、数字和 -_.；标签允许 [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}。空格、大写仓库名、未展开变量都会让 CLI 本地解析失败——报错发生在任何网络请求之前，与 daemon/镜像源/网络无关。
解法
echo打印最终镜像名，检查空格/大小写/变量展开；- 仓库名改全小写；去掉引号内多余空格；变量用
$(pwd)（PowerShell）或${PWD}（bash）正确展开； docker run alpine echo ok验证语法层通了，再回到原命令。
验证证据
- 本地实测（2026-08-31，WSL Ubuntu，docker CLI 29.1.3，本地 daemon 29.1.3）：
- 链 A：
docker run Ubuntu echo hi→docker: invalid reference format: repository name (library/Ubuntu) must be lowercase（exit 125）； - 链 B：
docker run "ubuntu " echo hi→docker: invalid reference format（短句形态）； - 对照：
docker run alpine echo ok→ 输出ok，exit 0，无语法报错。 - 实测复现日志（2026-08-31）
相关 canonical
按「前置 → 同根 / 同域 / 相关」读：
- 相关（报错相近，根因不同）：
- Docker daemon 连不上（先确认 daemon 活着，再查字符串；连接失败优先于引用解析）
适用工具 （1）
本问题方案已挂到下列工具的方案页——从工具页也能回到这里，双向可达。
docker · 外部工具来源与证据
← 编码代理与终端 问题域 ｜ 问题货架 ｜ 遇到其它问题？去 问题空间 提交求助卡