如何在WSL中运行Xdebug？配置后无法连接求解决方案及替代方案

一、排查现有配置的潜在问题 #

• 检查/etc/hosts中wsl.host的映射有效性：执行ping wsl.host，确认能正常连通Windows主机的WSL虚拟网卡IP。WSL重启后该IP可能变化，若不通需重新从/etc/resolv.conf获取最新nameserver值更新映射。
• 注意Xdebug版本参数适配：PHP7.3对应的Xdebug多为2.x版本，你当前配置混用了3.x参数（如xdebug.mode），这会导致配置失效。

二、修正Xdebug配置（适配PHP7.3+Xdebug2.x） #

编辑/etc/php/7.3/mods-available/xdebug.ini，替换为以下内容：

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_autostart=1
xdebug.remote_host=wsl.host
xdebug.remote_port=9000
xdebug.idekey=PHPSTORM

修改后重启PHP服务：

sudo service php7.3-fpm restart
# 若使用artisan serve，直接重启服务即可

三、PhpStorm配置调整 #

• 开启Xdebug监听：点击右上角电话图标，确保监听状态为开启。
• 配置服务器路径映射：
  1. 打开File > Settings > Languages & Frameworks > PHP > Servers
  2. 添加服务器，名称自定义（如WSL Laravel），主机填localhost，端口设为8000
  3. 勾选Use path mappings，将项目本地路径\\wsl$\Ubuntu\var\www\tr-archive映射到WSL内路径/var/www/tr-archive
• 验证调试配置：打开Run > Edit Configurations，添加PHP Web Page，选择已配置的服务器，设置起始URL为/，启动调试。

四、替代方案：直接使用Windows主机IP #

若wsl.host映射不稳定，可直接指定Windows主机物理IP：

1. Windows命令行执行ipconfig，找到当前联网网卡的IPv4地址（如192.168.1.100）
2. 修改Xdebug配置中的xdebug.remote_host为该IP：

xdebug.remote_host=192.168.1.100

3. 允许Windows防火墙9000端口入站：

New-NetFirewallRule -DisplayName "Xdebug" -Direction Inbound -LocalPort 9000 -Protocol TCP -Action Allow

五、额外注意事项 #

• 启动php artisan serve时，绑定到0.0.0.0而非127.0.0.1，确保Windows主机可访问：

php artisan serve --host=0.0.0.0 --port=8000

• 确认PhpStorm的Xdebug端口设置为9000，需与Xdebug配置中的xdebug.remote_port保持一致。

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