Docker环境下Xdebug正常但PHPUnit调试失败求助

核心配置检查 #

• 确认Xdebug与宿主机连通
  Docker容器里的Xdebug不能用localhost指向宿主机，Windows/macOS直接设xdebug.client_host=host.docker.internal，Linux则填宿主机的局域网IP（比如192.168.3.10）。完整示例配置：

  xdebug.mode=debug
  xdebug.client_host=host.docker.internal
  xdebug.client_port=9003
  xdebug.start_with_request=yes
  

• 修正PHP_IDE_CONFIG参数
  这个参数必须和PhpStorm里「Settings > Languages & Frameworks > PHP > Servers」的服务器名称完全一致，格式是serverName=你的服务器名。
  可以直接写进容器的php.ini：

  PHP_IDE_CONFIG="serverName=local-api-server"
  

  或者启动容器时用环境变量传：

  docker run -e PHP_IDE_CONFIG="serverName=local-api-server" 你的镜像名
  

PhpStorm调试配置调整 #

• 验证PHPUnit路径映射
  进「Settings > Languages & Frameworks > PHP > Test Frameworks」，选中你的PHPUnit配置，检查「Path mappings」：容器内的项目根目录（比如/var/www/html）必须对应本地项目的根目录，一点错都不能有。
• 调试启动前必做
  点击调试按钮前，先激活PhpStorm右上角的「Start Listening for PHP Debug Connections」（电话图标），没开这个肯定连不上Xdebug。

异常场景针对性修复 #

• 运行按钮执行测试异常
  运行按钮默认不触发调试，要让它带调试的话，打开PHPUnit的运行配置，在「Debug」标签页勾选「Enable Xdebug」，或者在「Environment variables」里加XDEBUG_MODE=debug。
• 调试按钮触发异常
  开Xdebug日志查问题，在php.ini里加：

  xdebug.log=/var/log/xdebug.log
  

  看日志里有没有连接失败、路径找不到的记录，比如提示“Could not connect to client host”就是client_host设错了，提示“File not found”就是路径映射没配对。

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