Docker内运行YOLOv5调用摄像头报Qt xcb显示错误如何解决

这个报错核心是两个问题：

1. 安装的OpenCV默认绑定Qt GUI组件，启动时要连接X11显示服务，但Docker容器默认隔离了宿主的显示套接字、没配置DISPLAY环境变量，连不上显示服务就会加载xcb插件失败。
2. 现有Dockerfile存在两个硬伤：一是缺全量X11依赖，二是用的python:latest是x86架构镜像，没法在arm64架构的Jetson Nano上原生运行，也调用不了Jetson的GPU加速。

方案1：无头运行（无GUI，生产部署推荐） #

如果不需要弹出实时推理窗口，只需要保存推理结果、做后端逻辑处理或者推流，直接绕开GUI依赖就行，完全不用折腾X11配置：

1. 调整依赖：把requirements.txt里的opencv-python替换成opencv-python-headless，这个版本不带Qt GUI组件，从根源上避免xcb报错。
2. 调整Dockerfile：
   • 把基础镜像换成Jetson适配的arm64版本镜像，不要用官方python:latest，比如JetPack 4.6版本对应nvcr.io/nvidia/l4t-pytorch:r32.7.1-pth1.10-py3，Windows x86测试可以继续用python镜像。
   • 加无头模式环境变量，修改后的Dockerfile参考：

   # 注意Jetson部署要换对应JetPack版本的Nvidia L4T镜像，x86测试可以用python:3.10-slim
   FROM nvcr.io/nvidia/l4t-pytorch:r32.7.1-pth1.10-py3
   WORKDIR /yolov5_aiss
   # 配置OpenCV无头运行
   ENV QT_QPA_PLATFORM=offscreen
   ENV OPENCV_IO_MAX_IMAGE_PIXELS=1000000000
   
   COPY requirements.txt . 
   RUN pip3 install -r requirements.txt
   
   COPY ./app ./app
   RUN apt-get update -y && apt-get install -y --no-install-recommends \
       ffmpeg libsm6 libxext6 \
       && rm -rf /var/lib/apt/lists/*
   
   # 注意不要加--view-img参数，这个参数会触发GUI弹窗
   CMD ["python", "./app/detect.py", "--weights","./app/weights/best.pt", "--source", "0"]
   

3. 运行容器时正确挂载设备：
   • Windows（Docker Desktop）：先在Docker Desktop设置-资源-摄像头里开启摄像头权限，运行命令加--device /dev/video0
   • Jetson Nano：必须加nvidia runtime调用GPU，挂载摄像头设备，参考运行命令：

   sudo docker run --runtime nvidia -it --rm \
     --device /dev/video0 \
     你的镜像名:标签
   

方案2：需要弹出实时推理GUI窗口 #

如果要在宿主屏幕上显示实时画框的推理画面，需要透传宿主的X11显示服务：

1. 补全Dockerfile里的X11依赖，把apt安装段替换成：

   RUN apt-get update -y && apt-get install -y --no-install-recommends \
       ffmpeg libsm6 libxext6 libxkbcommon-x11-0 libxcb1 libxcb-glx0 \
       libxcb-keysyms1 libxcb-image0 libxcb-shm0 libxcb-icccm4 \
       libxcb-sync1 libxcb-xfixes0 libxcb-shape0 libxcb-randr0 \
       libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 libxrender1 \
       && rm -rf /var/lib/apt/lists/*
   

2. 运行前给容器开放X服务权限：
   • Jetson（Linux环境）：宿主终端先执行xhost +local:root
   • Windows环境：先安装VcXsrv/Xming这类X服务端，启动时关闭访问控制。
3. 运行容器时透传显示配置和设备：
   • Jetson运行命令参考：

   sudo docker run --runtime nvidia -it --rm \
     -e DISPLAY=$DISPLAY \
     -v /tmp/.X11-unix:/tmp/.X11-unix \
     -v $HOME/.Xauthority:/root/.Xauthority \
     --net=host \
     --device /dev/video0 \
     你的镜像名:标签
   

   • Windows运行时把DISPLAY变量设为-e DISPLAY=host.docker.internal:0.0即可。

• 先在容器内单独测试摄像头是否能正常读取：进入容器终端执行python -c "import cv2; cap = cv2.VideoCapture(0); print('摄像头状态：', cap.isOpened())"，如果返回False说明设备没挂载对，和Qt/xcb报错无关。
• 如果用CSI摄像头，Jetson上需要额外挂载/dev/nvhost-*、/dev/tegra*相关设备，测试阶段可以直接加--privileged参数给足权限，生产环境再按需裁剪。
• 如果还是报xcb错误，直接执行pip uninstall opencv-python && pip install opencv-python-headless重装无GUI版本的OpenCV，切回头模式运行即可。

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