docker 报 invalid reference format / repository name must be lowercase（镜像引用格式非法）

症状

```

# 形态 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/镜像源/网络无关。

解法

1. `echo` 打印最终镜像名，检查空格/大小写/变量展开；

2. 仓库名改全小写；去掉引号内多余空格；变量用 `$(pwd)`（PowerShell）或 `${PWD}`（bash）正确展开；

3. `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）