Docker环境下XDebug无法连接VSCode的调试问题求助
解决Docker + VSCode + XDebug连接失败的问题
我来帮你理一理这个问题,核心就是Docker容器和Windows主机之间的网络寻址错误,你踩的坑很多Docker新手都会遇到,别着急,按下面的步骤来排查修复:
关键问题分析
你用了xdebug.remote_connect_back=1,这个配置会让XDebug自动获取请求的REMOTE_ADDR作为调试主机地址,但容器里拿到的172.20.0.1其实是Docker网桥的网关IP,不是Windows主机的真实可访问IP。Windows的Docker网络结构里,容器要访问主机,得用DockerNAT网卡的IP(你这里是10.0.75.1)或者Docker提供的特殊域名host.docker.internal。
具体修复步骤
修改XDebug配置,指定正确的调试主机
打开你的php-ini-overrides.ini,做如下修改:upload_max_filesize = 100M post_max_size = 108M # added for debugging with Docker and VSCode xdebug.remote_enable=1 # 注释掉remote_connect_back,因为它拿到的是网关IP,不是主机IP # xdebug.remote_connect_back=On # xdebug.remote_connect_back=1 xdebug.remote_autostart=1 # 使用Docker提供的特殊域名(Windows Docker支持),或者直接写你的DockerNAT IP 10.0.75.1 xdebug.remote_host=host.docker.internal xdebug.remote_port=9001 xdebug.profiler_enable=0 xdebug.var_display_max_depth = 5 xdebug.var_display_max_children = 256 xdebug.var_display_max_data = 1024 xdebug.remote_log = /application/xdebug.log xdebug.idekey = VSCODE重启php-fpm容器让配置生效
在主机终端执行:docker-compose restart php-fpm验证容器到主机的网络连通性
进入php-fpm容器,测试VSCode监听的9001端口是否能连通:docker-compose exec php-fpm bash nc -zv host.docker.internal 9001如果返回成功,说明网络通了;如果还是失败,就换成你的DockerNAT IP
10.0.75.1测试:nc -zv 10.0.75.1 9001确认VSCode配置无误
检查你的launch.json:port必须和XDebug的remote_port一致(都是9001)pathMappings要确保容器内的路径和主机路径对应正确,你这里的"/application/public": "${workspaceRoot}/public"是对的,因为php-fpm容器的工作目录是/application
重新测试断点
启动VSCode的调试监听,然后访问网页(用10.0.75.1:8000),应该就能触发断点了。
额外说明
host.docker.internal是Docker为Windows/macOS主机提供的特殊域名,自动映射到主机的IP,比手动写IP更灵活- 你之前关闭防火墙是对的,确保主机的9001端口没有被拦截
- 从XDebug日志里能明确看到它一直在尝试连接
172.20.0.1,这就是问题根源,修改remote_host后日志里应该会显示连接host.docker.internal或者10.0.75.1
内容的提问来源于stack exchange,提问作者Nico Kempe




