Mac端PhpStorm调试远程Ubuntu服务器Sail容器Laravel报Xdebug Broken pipe错误

前置分析 #

从提供的Xdebug日志可确认：Xdebug已成功建立到9003端口的网络连接，但发送初始化数据后立即断开，说明网络通路无问题，故障出在IDE侧的配置校验或路径映射不匹配。

排查步骤 #

• 校验IDE密钥匹配 #

  日志中Xdebug使用的idekey为phpstorm，需确认PhpStorm侧配置一致：
  1. 打开设置 > PHP > 调试，确认Xdebug调试端口设置为9003，已勾选「接受外部连接」
  2. 打开设置 > PHP > 服务器，找到对应远程服务器配置，IDE密钥填写phpstorm

• 修正路径映射配置（90%以上故障根因） #

  日志显示容器内代码根路径为/var/www/html，需在PhpStorm远程服务器配置中勾选「使用路径映射」，将本地Mac端Laravel项目根目录，映射到容器内的/var/www/html路径，确保所有子目录映射关系一一对应，无遗漏。

• 校验SSH反向隧道配置 #

  远程服务器部署场景需使用反向隧道将远程9003端口流量转发到本地Mac：
  1. 确认隧道命令使用-R参数，正确命令为 ssh -N -R 9003:localhost:9003 远程服务器用户名@远程服务器IP
  2. 隧道建立后在远程服务器执行 lsof -i :9003，确认9003端口已被SSH进程监听

• 修正Sail Xdebug配置 #

  关闭自动客户端地址发现，避免连接到错误公网IP：
  1. 在Laravel项目.env文件中添加/修改配置：

  SAIL_XDEBUG_MODE=debug
  SAIL_XDEBUG_CONFIG="client_host=host.docker.internal idekey=phpstorm discover_client_host=false"
  

  2. 执行sail restart重启容器使配置生效

• 本地网络权限排查 #

  1. 临时关闭Mac系统防火墙及第三方安全软件，测试是否拦截了9003端口流量
  2. 本地终端执行nc -l 9003监听端口，触发远程应用请求，若终端收到Xdebug的XML格式数据，说明网络通路正常，故障集中在PhpStorm配置侧。

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