如何用VSC调试本地Docker容器中运行的PHP代码？

核心排查与修复步骤 #

1. 修正Xdebug的主机地址配置 #

Windows环境下host.docker.internal偶尔会出现解析异常，直接替换为主机的实际局域网IPv4地址：

• 打开CMD执行ipconfig，找到本地网卡的IPv4地址（例如192.168.3.12）
• 修改容器内xdebug.ini配置：

zend_extension=xdebug
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host=192.168.3.12  # 替换为你的主机实际IP
xdebug.client_port=9003
xdebug.log=/var/log/xdebug.log  # 保留日志用于后续排查

重启PHP容器使配置生效。

2. 调整VSCode的launch.json配置 #

• 删除多余的hostname字段，Xdebug是主动发起连接，VSCode仅需监听指定端口
• 确保pathMappings的路径完全匹配，统一用正斜杠避免Windows路径解析问题：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Docker Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "stopOnEntry": true,
      "pathMappings": {
        "/var/www/amc/plattform": "${workspaceFolder}/amc"
      },
      "log": true  // 开启VSCode调试日志，方便定位问题
    }
  ]
}

3. 检查防火墙与端口占用 #

• 打开Windows防火墙，允许VSCode或php-debug插件接收9003端口的入站连接
• 执行netstat -ano | findstr :9003确认端口未被其他程序占用，若被占用，将Xdebug和launch.json的端口统一改为其他值（比如9004）

4. 验证Docker网络配置 #

• 若使用自定义Docker网络，确保容器与主机处于同一网络段
• 不要对9003端口做Docker端口映射（Xdebug是容器主动连接主机，而非主机连接容器），避免端口冲突
• 若配置了extra_hosts，确保映射的IP与Xdebug配置一致：

# docker-compose示例配置
services:
  php:
    extra_hosts:
      - "host.docker.internal:192.168.3.12"  # 和xdebug.client_host保持相同

5. 确认断点与路径匹配 #

• 访问xdebug_info()页面，查看Connected Client是否显示主机IP和9003端口
• 若Xdebug日志显示Connected to client但VSCode无响应，检查：
  • 本地项目文件路径是否与pathMappings完全对应（比如容器内/var/www/amc/plattform/index.php对应本地${workspaceFolder}/amc/index.php）
  • 断点是否设置在实际会被执行的代码行（不要设置在注释、空行或未调用的函数上）

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