在Docker中运行带界面的Playwright测试时遇XServer报错求助

排查步骤与解决方案 #

1. 确认DISPLAY变量配置正确性 #

进入容器后执行 echo $DISPLAY，检查输出是否为 host.docker.internal:0。如果该变量未正确传递，重新运行容器时需确保环境变量参数无误。
若host.docker.internal解析异常，替换为本地Mac的实际IP（可通过ipconfig getifaddr en0获取），示例命令：

docker run --rm \
        --name e2e-on-docker-container \
        -e HTTPS=false \
        -e DISPLAY=192.168.1.100:0 \
        -it -p 3000:3000 \
        -v /tmp/.X11-unix:/tmp/.X11-unix \
        e2e-on-docker-image /bin/bash

2. 验证XQuartz网络访问权限 #

• 打开XQuartz偏好设置→「安全性」标签，确保允许网络客户端连接已勾选
• 重启XQuartz，在本地终端执行 xhost +（临时开放权限，测试完成后可执行xhost -恢复安全设置）
• 执行 xhost 命令，确认输出包含localhost或容器IP，验证权限已开放

3. 检查Docker Desktop文件访问权限 #

• 打开Docker Desktop偏好设置→「资源」→「文件共享」，确认/tmp/.X11-unix已添加到共享列表，且Docker拥有访问权限
• 若未添加，完成添加后重启Docker Desktop

4. 验证容器与本地XServer的连接 #

进入容器后，安装X11测试工具：

apt-get update && apt-get install -y x11-apps

执行 xeyes，若本地XQuartz窗口能显示眼睛动画，说明X连接正常；若无法显示，回到前两步排查配置问题。

5. 排除容器内Xvfb的干扰 #

如果镜像中安装了Xvfb，但目标是将界面映射到本地XQuartz，需确保容器内未自动启动Xvfb服务，且DISPLAY变量未指向Xvfb（如:1），保持指向本地XServer。

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