Docker容器运行GUI程序时报invalid reference format错误是什么原因？

错误原因 #

该报错由shell命令参数解析异常导致，Docker误将运行命令的参数识别为镜像名称，常见触发场景如下：

• 续行符后存在多余字符：你使用\作为命令换行的续行符时，\后面不能紧跟任何空格、制表符，必须直接换行。如果\后有多余空格，shell会将下一行内容识别为独立指令片段，Docker就会把后续参数误判为镜像名，触发小写校验报错。
• 环境变量值异常：执行echo $DISPLAY检查当前环境的DISPLAY变量值是否包含空格、引号等特殊字符，异常的变量值会打断参数的正常拆分，同样会触发该报错。

修复方案 #

1. 删除所有续行符\后的多余空格，保证每一行末尾的\是该行最后一个字符，也可以直接将整条命令写在同一行测试：

docker run -v /tmp/.X11-unix:/tmp/.X11-unix -h $HOSTNAME -v $HOME/.Xauthority:/home/$USER/.Xauthority -e DISPLAY=$DISPLAY gui

2. 运行容器前执行xhost +local:docker允许本地容器进程连接X服务器，避免后续Firefox启动时出现权限报错。
3. 确认Dockerfile中占位符<USERNAME>、UID、GID已替换为和宿主机当前用户一致的实际值，否则挂载.Xauthority文件时会出现权限不匹配问题。

内容的提问来源于stack exchange，提问作者KammO