Docker 挂载含空格路径时报 invalid reference format

镜像名明明是小写，docker run 仍然返回下面的错误，而且换到另一个项目目录后又能运行：

invalid reference format: repository name must be lowercase

如果命令在 -v 后使用了没有双引号的 $(pwd) 或路径变量，要检查目录名中的空格。shell 可能已把一个挂载参数拆成多个参数，Docker 接收到的“镜像名”因此成了路径的一部分。

本文针对 Bash、POSIX sh 这类按字段分割规则处理未引用展开结果的环境，并假定使用通常的空白分隔设置。PowerShell、Windows CMD 和其他 shell 的解析规则不同，不应直接套用这里的语法。

错误指向镜像，起因可能在前面的挂载参数

以下是容易出错的写法，仅用于说明，不要直接执行：

docker run --rm -v $(pwd)/app:/work approved-image:known-good

假设当前目录是 /home/user/Project Files，shell 对未引用的命令替换结果进行分割后，原本要交给 -v 的值会被拆成：

/home/user/Project
Files/app:/work

Docker 的命令结构是选项之后跟镜像，再跟容器内命令及其参数。-v 只能取得后面的一个参数，多出来的 Files/app:/work 就可能落到镜像位置，并在解析引用格式时被拒绝。你原本填写的 approved-image:known-good 反而成了更后面的参数。

因此，这种情况下把真实镜像名改成小写不会解决问题；真实镜像名已经不是 Docker 正在尝试解析的那个参数。具体错误文字取决于被拆出的字符串，可能只有 invalid reference format，不一定带小写提示。

在命令失败的目录里确认路径：

pwd
printf '<%s>\n' "$(pwd)/app:/work"

尖括号只是显示边界，不能证明原命令已经正确引用；第二条展示的是引用后的完整值。还要回到脚本、终端历史或 CI 命令本身，看实际传给 -v 的展开表达式外是否有双引号。

把完整挂载值作为一个参数传入

修复 -v 写法时，将整个挂载参数放进双引号：

docker run --rm -v "$(pwd)/app:/work" approved-image:known-good

这里假设当前项目的 app 目录确实存在，镜像和启动方式也已经核实。approved-image:known-good 是占位镜像名，必须换成原来经过确认的镜像；保留原命令中的其他选项、工作目录和容器内命令，不要仅复制这一行替换完整业务启动命令。

双引号允许 $(pwd) 展开，同时保留结果里的空格。写成单引号会把 $(pwd) 当成字面文本，不能得到当前目录；中文弯引号也不能替代 shell 的英文双引号。

使用变量时，赋值和后续展开都要留意引用：

source_dir="$(pwd)/app"
printf '<%s>\n' "$source_dir:/work"

实际 -v 参数应写成 "$source_dir:/work"。不要把整条 Docker 命令拼成一个字符串再用 eval 执行：那会增加一轮 shell 解析，使引号更难维护。

用只读挂载核对路径

先在测试环境确认路径能正确传递，再恢复需要写入的业务操作。使用现代 Docker CLI 时，也可以用更明确的 --mount 语法。下面同样只演示参数组织，镜像须替换成已批准、启动行为已知的测试镜像：

source_dir="$(pwd)/app"
docker run --rm \
  --mount "type=bind,src=${source_dir},dst=/work,readonly" \
  approved-image:known-good

整个 --mount 值仍要作为一个 shell 参数传递。这个示例处理空格；如果路径含逗号等 --mount 自身语法使用的字符，还需要按该选项的格式处理，不能把 shell 引号当成所有特殊字符的通用转义。

readonly 阻止容器通过该挂载修改宿主机内容，适合只读检查。它不会阻止容器读取挂载目录，也不会约束镜像的其他启动行为，所以应使用无敏感内容的测试目录。需要在项目目录生成产物的构建任务可能因只读而失败，这不表示空格问题仍未修好。

检查时确认容器看到的是 /work 下预期的测试文件，而不是另一个空目录。默认情况下，--mount 的源路径不存在会报错；-v 对不存在的宿主机路径则可能创建目录。这是两种选项的行为差异，换用 --mount 后应重新核对源路径。

路径属于 Docker daemon 所在主机。连接远程 daemon 时，本机 pwd 的结果不代表远端存在同一路径；Docker Desktop 对本机路径共享有额外支持，不能据此推断任意远程服务器都能访问本机目录。

格式修正后按新的错误继续判断

引号修正后，原来的引用格式错误应消失。接下来若出现镜像不存在、挂载源不存在、共享目录未授权或权限拒绝，就根据新的报错检查对应环节。不要为了修复参数分割，重命名整棵项目目录、删除容器数据卷或放宽目录权限。

这类修改本身只涉及命令或脚本，可以保留旧文本用于比对。不过，重新运行修正后的命令可能真正启动应用、执行构建或写入挂载目录；先在测试目录验证，并保留需要写入的数据备份。恢复旧脚本文本不会撤销已经生成或修改的宿主机文件。