VS Code PHP调试器搭配Docker使用无法触发断点问题求助

问题排查与解决方案 #

从提供的Xdebug日志可以确认，Xdebug已成功与VS Code的9003端口建立连接，且发送了调试初始化报文，但未收到VS Code的响应，因此请求持续挂起，停止调试器后连接中断，请求才正常返回。可按以下顺序排查修复：

• 确认PHP Debug扩展版本兼容性
  你使用的是Xdebug 3.0.4，需保证VS Code安装的PHP Debug扩展版本≥1.14.0，旧版本扩展无法兼容Xdebug 3的通信协议，会出现收到初始化报文无响应的问题。

• 补充Xdebug配置缺失参数
  修改Dockerfile中Xdebug配置段，补充两行配置：

echo 'xdebug.idekey=VSCODE'; \
echo 'xdebug.discover_client_host=0'; \

避免idekey不匹配，或Xdebug自动检测客户端地址覆盖host.docker.internal配置。

• 调整VS Code launch.json配置

  1. 确认路径映射正确性：如果Windows本地工作目录存在盘符、大小写问题，可将${workspaceFolder}替换为本地目录的绝对路径，示例：

  "pathMappings": {
      "/var/www/html/": "C:\\project\\php-demo"
  }
  

  2. 给Listen for Xdebug配置段添加idekey匹配：

  "idekey": "VSCODE"
  

• 检查Windows防火墙规则
  临时关闭Windows Defender防火墙测试，如果调试恢复正常，给VS Code添加9003端口的入站允许规则即可。

• 验证调试触发逻辑
  你配置了xdebug.start_with_request=yes，所有请求都会触发调试，可先开启VS Code PHP Debug设置中的Stop at First Line选项，测试调试器能否正常在代码第一行断住，排除断点位置匹配错误的问题。

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