Docker环境下VS Code中Xdebug无法在断点处停止的问题排查

既然PhpStorm能正常触发断点，说明Xdebug本身的安装和基础配置没问题，问题大概率出在VS Code的调试配置或容器与主机的通信上，你可以从以下几个方面排查：

1. 修正pathMappings的映射方向 #

你的pathMappings写反了！VS Code的pathMappings规则是容器内的代码路径作为键，本地主机的代码路径作为值——Xdebug在容器中运行时，会向调试器报告容器内的文件路径，VS Code需要把这个路径映射到你本地的对应文件。

你当前的配置：

"pathMappings": {
    "/home/myuser/projects/myproject": "/application"
}

应该改成：

"pathMappings": {
    "/application": "/home/myuser/projects/myproject"
}

2. 确保Xdebug能访问到主机的VS Code调试端口 #

Docker容器默认无法直接通过localhost访问主机的服务，你需要：

• 在容器的Xdebug配置中设置xdebug.client_host为主机的内网IP（比如172.17.0.1，可通过ip addr show docker0在主机上查看），或者使用host.docker.internal（Docker Desktop支持，部分Linux环境需要配置--add-host host.docker.internal:host-gateway启动容器）。
• 确认主机的9003端口没有被防火墙或其他服务占用，可在主机上执行netstat -tulpn | grep 9003检查VS Code是否在监听这个端口。

3. 验证Xdebug的端口配置 #

确认容器内Xdebug的client_port和VS Code的监听端口一致：
在容器内执行命令：

php -i | grep xdebug.client_port

如果输出不是9003，需要调整VS Code的port配置，或者在容器环境变量中设置XDEBUG_CONFIG="client_port=9003"。

4. 检查VS Code的PHP Debug插件状态 #

• 确保安装的是官方的PHP Debug插件（作者是Felix Becker），并且是最新版本。
• 调试前要点击VS Code左侧的调试面板，选中Listen for Xdebug配置，然后点击启动按钮（绿色三角），确保调试器处于监听状态。

5. 确认调试触发方式 #

使用Listen for Xdebug配置时，需要主动触发Xdebug的调试请求：

• 如果是Web应用，安装浏览器的Xdebug辅助扩展（比如Xdebug Helper），开启调试模式后再访问页面。
• 如果是CLI脚本，在容器内执行脚本时，要加上环境变量：XDEBUG_MODE=debug php your_script.php。

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