Docker环境下Xdebug命令行客户端无法触发WordPress断点求助

以下是针对你遇到问题的具体排查方向：

• 断点路径必须匹配容器内路径
  VSCode会自动配置本地与Docker容器的路径映射，但Xdebug命令行客户端没有这个自动处理逻辑。执行breakpoint_set时，必须使用容器内的绝对文件路径（例如/var/www/html/wp-content/themes/your-theme/index.php），而非本地机器的路径。如果路径不匹配，Xdebug无法定位断点，会导致请求一直挂起等待调试器响应。

• 手动触发Xdebug调试会话
  VSCode会自动处理调试触发的Cookie或参数，但命令行客户端需要手动触发调试会话：

  • 在浏览器访问页面时，在URL后添加?XDEBUG_SESSION=1
  • 或者在浏览器中设置名为XDEBUG_SESSION、值为任意内容的Cookie
    确保执行run命令后，再触发这个请求，否则Xdebug不会将调试事件发送到命令行客户端。

• 检查breakpoint_set的语法正确性
  确认DBGp协议的断点命令格式无误，正确示例：

  breakpoint_set -i 1 -t line -f /var/www/html/wp-content/plugins/your-plugin/script.php -n 30
  

  其中：

  • -i 指定会话ID（首次连接可设为1）
  • -t line 声明是行断点
  • -f 后跟容器内的目标文件绝对路径
  • -n 指定断点所在行号
    任何参数错误都会导致断点无法生效。

• 验证调试会话状态
  执行run命令后，如果浏览器卡住，可在命令行客户端输入status查看当前会话状态：

  • 如果显示"waiting for connection"，说明Xdebug未正确连接到客户端，检查xdebug.client_host是否指向宿主机（Docker环境下通常用host.docker.internal或宿主机内网IP）
  • 如果显示"running"，说明断点未命中，检查路径、行号是否正确，或者代码是否真的被执行到。

• 尝试用continue替代run命令
  部分场景下，run命令可能会导致会话阻塞，试试先执行breakpoint_set，待Xdebug连接后输入continue，再触发浏览器请求，看是否能命中断点。

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