WSL2下Laradock+PhpStorm的Xdebug连接超时问题求助

核心问题：Xdebug版本参数不兼容 #

你的报错信息显示使用的是Xdebug 3.x（日志中提到xdebug.client_host/xdebug.client_port），但当前xdebug.ini配置用的是Xdebug 2.x的remote_*系列参数，两者不匹配是导致连接超时的主要原因。

第一步：更新Xdebug配置（适配Xdebug 3.x） #

替换laradock/workspace目录下的xdebug.ini为以下内容：

; Xdebug 3.x核心调试配置
xdebug.mode=debug
xdebug.client_host=WSL_INSTANCE_IP
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

; 调试触发规则（替代原remote_autostart）
xdebug.start_with_request=trigger

; 其他保留配置
xdebug.discover_client_host=0
xdebug.cli_color=0
xdebug.profiler_enable=0
xdebug.profiler_output_dir="~/xdebug/phpstorm/tmp/profiling"

; 变量显示优化
xdebug.var_display_max_children=-1
xdebug.var_display_max_data=-1
xdebug.var_display_max_depth=-1

• WSL_INSTANCE_IP替换为你的WSL2实例IP：在WSL终端执行hostname -I获取，通常是172.xx.xx.xx格式的地址。
• Xdebug 3.x默认调试端口为9003，避开了PHP-FPM默认占用的9000端口，减少冲突概率。

第二步：验证网络连通性 #

1. 进入Laradock的workspace容器，执行ping WSL_INSTANCE_IP，确认容器能正常连通WSL实例。
2. 检查Windows防火墙：允许PhpStorm通过防火墙，或临时关闭防火墙测试是否能建立连接。
3. 排查端口占用：在WSL终端执行lsof -i :9003，确认该端口未被其他程序占用。

第三步：PhpStorm配置检查 #

1. 开启调试监听：点击PhpStorm右上角的电话图标，确保监听状态为激活。
2. 匹配调试端口：进入File > Settings > Languages & Frameworks > PHP > Debug，将Xdebug > Debug port设置为9003，勾选Can accept external connections。
3. 配置路径映射：在File > Settings > Languages & Frameworks > PHP > Servers中，确保本地项目路径与容器内项目路径（通常为/var/www）一一对应。

第四步：使配置生效 #

重启Laradock的workspace容器：

cd laradock
docker-compose restart workspace

随后在容器内执行php -v确认Xdebug 3.x已加载，或通过项目的phpinfo()页面验证Xdebug参数是否与配置一致。

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