WSL2+Docker环境下Xdebug连接地址错误无法对接VSCode问题

172.20.112.1地址来源 #

这个地址是WSL2虚拟网络的动态网关地址，你开启了xdebug.remote_connect_back=1配置，该配置优先级高于xdebug.remote_host，Xdebug会自动读取HTTP请求的REMOTE_ADDR头（也就是WSL网关地址）作为调试目标地址，该地址由WSL动态生成，默认不会在路由表、hosts文件中静态配置。

问题修复步骤 #

第一步：解决WSL与Docker Desktop版本不一致问题 #

你遇到的版本冲突是因为WSL内部单独安装过旧版本Docker，和Docker Desktop的集成服务冲突：

• 卸载WSL内部的旧Docker：在WSL终端执行sudo apt remove docker-ce docker-ce-cli containerd.io
• 打开Docker Desktop设置，开启「Use the WSL 2 based engine」，再进入「Resources > WSL Integration」页面，打开对应WSL发行版的集成开关，重启Docker Desktop
• 重启后在WSL终端执行docker -v，确认版本和Windows端一致，此时host-gateway参数即可正常生效

第二步：修正Xdebug配置 #

你当前的Xdebug配置存在冲突，按以下方式修改：

xdebug.extended_info=on
xdebug.idekey=xdebug
xdebug.profiler_enable=off
xdebug.profiler_enable_trigger=on
xdebug.remote_autostart=1
# 关闭remote_connect_back，优先使用指定的remote_host
xdebug.remote_connect_back=0
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=host.docker.internal
xdebug.remote_log="/var/log/xdebug.log"
xdebug.remote_port=9001

注意：Xdebug是容器主动向宿主机发起连接，不需要在Dockerfile、docker-compose中暴露9001端口，可删除对应暴露配置避免端口冲突。

第三步：配置Windows防火墙规则 #

打开Windows Defender防火墙高级设置，添加入站规则：

• 规则类型选「端口」，协议选TCP，特定本地端口填9001
• 允许连接，网络范围选WSL对应的子网（通常是172.16.0.0/12段）
• 保存规则后重启VSCode，开启Xdebug监听即可正常连接

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