如何让VSCode连接Docker环境下的Xdebug（PHP7.2/Xdebug2.6.0）

我之前也碰到过几乎一模一样的情况，结合你给出的PHP 7.2、Xdebug 2.6.0、VSCode调试适配器1.12.1的环境信息，咱们一步步来定位和解决问题：

一、先核对Xdebug核心配置（容器内的php.ini） #

Xdebug 2.x的配置和3.x差异很大，这是最容易踩坑的点，确保你的配置包含这些关键项：

xdebug.remote_enable = 1
xdebug.remote_connect_back = 0  # 必须设为0，不然Xdebug会用容器内的IP去连接，找不到宿主机
xdebug.remote_host = 宿主机IP   # 比如Docker网关IP（一般是172.17.0.1），或者Docker Desktop用host.docker.internal
xdebug.remote_port = 9000       # 和VSCode调试端口保持一致
xdebug.remote_autostart = 1     # 自动触发调试，不用手动加cookie
xdebug.log = /var/log/xdebug.log
xdebug.log_level = 7            # 设为最高日志级别，方便排查

注意：要确保/var/log/xdebug.log文件存在且容器内的PHP进程有写入权限，不然日志根本生成不了。

二、检查VSCode的launch.json配置 #

pathMappings是重中之重，必须把本地项目路径和容器内的路径精准对应，否则Xdebug找不到本地的代码文件，调试就没反应。示例配置如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"  # 左边是容器内项目路径，右边是本地项目根目录
            },
            "log": true  # 开启VSCode调试日志，方便看连接情况
        }
    ]
}

三、排查网络连通性 #

既然你在容器内运行脚本时Xdebug正常，说明Xdebug本身没问题，大概率是容器到宿主机的网络不通：

• 进入php-fpm容器，执行telnet 宿主机IP 9000，如果连接失败，说明宿主机的防火墙挡住了9000端口，或者Docker网络模式限制了访问；
• 如果是Docker Desktop环境，直接用host.docker.internal作为xdebug.remote_host的地址，它会自动映射到宿主机IP；
• 如果是Linux环境，用ip addr show docker0查看Docker网关IP，把这个IP设为xdebug.remote_host。

四、验证调试触发逻辑 #

VSCode显示success: true只是说明调试适配器在监听端口，但Xdebug需要被触发才会发起连接：

• 如果没开xdebug.remote_autostart=1，需要在浏览器里加XDEBUG_SESSION_START=VSCODE的Cookie，或者用浏览器插件（比如Xdebug Helper）来触发；
• 调试CLI脚本的话，要确保启动脚本时加上-dxdebug.remote_autostart=1参数，或者在php.ini里全局开启自动触发。

最后再做一次验证流程 #

1. 重启php-fpm容器，让Xdebug配置生效；
2. 打开VSCode的调试面板，启动"Listen for Xdebug"；
3. 在本地代码里打个断点，然后访问对应页面或执行CLI脚本；
4. 查看容器内的/var/log/xdebug.log，如果有连接日志，说明配置没问题了。

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