PhpStorm Debug模式运行单元测试失败 Xdebug连接超时

你当前场景下浏览器常规调试可正常运行，说明Xdebug基础安装、路径映射、端口监听的核心配置无异常，故障集中在CLI模式运行PHPUnit Debug的链路，按以下顺序排查修复即可：

• 调大Xdebug连接超时阈值
  报错信息显示Xdebug仅等待200ms就判定连接失败，WSL2+Docker的跨网络栈转发本身存在额外开销，200ms阈值很容易触发超时。进入运行PHPUnit的Docker容器，修改xdebug.ini配置，新增或调整以下参数：

  xdebug.connect_timeout_ms = 1000
  

  修改完成后重启容器让配置生效。
• 修复进程隔离导致的Xdebug环境变量丢失问题
  你提供的phpunit配置中processIsolation="true"，该配置会让PHPUnit为每个测试用例启动独立的PHP子进程，默认不会继承父进程的Xdebug相关环境变量，最终导致子进程无法正确连接调试客户端。两种修复方案二选一即可：
  1. 调试阶段临时关闭进程隔离：将phpunit.xml中的processIsolation值改为false，调试完成后再改回原值
  2. 保留进程隔离配置：在phpunit.xml的<php>节点下显式注入Xdebug所需环境变量，示例配置：

     <php>
         <env name="XDEBUG_MODE" value="debug,develop"/>
         <env name="XDEBUG_SESSION" value="1"/>
         <env name="XDEBUG_CONFIG" value="client_host=host.docker.internal client_port=9000 connect_timeout_ms=1000"/>
     </php>
     

• 校验PhpStorm端CLI解释器配置
  打开PhpStorm设置页，依次进入Settings > PHP > CLI Interpreter，选中你当前使用的Docker对应解释器，确认项目本地路径（含WSL挂载路径）和容器内项目路径的映射完全正确；再进入Settings > PHP > Debug页，确认Xdebug监听端口为9000，勾选Can accept external connections选项，同时确认9000端口没有被其他程序占用。触发Debug前记得点亮PhpStorm顶部工具栏的电话图标，开启调试连接监听。
• 修复容器内host.docker.internal解析异常
  进入运行PHPUnit的容器，执行ping host.docker.internal校验域名解析是否正常，如果解析失败，调整容器启动参数新增hosts映射：
  直接用docker启动的话添加参数：

  --add-host=host.docker.internal:host-gateway
  

  用docker-compose编排的话在对应服务下添加配置：

  extra_hosts:
    - host.docker.internal:host-gateway
  

修复完成后，可以先在容器内手动执行带调试参数的phpunit命令验证，确认无超时报错后，再回到PhpStorm触发Debug模式运行单元测试。

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