Laravel Sail（WSL+Docker）配置Xdebug浏览器调试失败求助

针对你遇到的Xdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003错误，可按以下步骤排查解决：

1. 修正WSL环境下的Xdebug客户端主机地址 #

WSL2网络环境中，host.docker.internal可能无法正确映射到Windows主机，需手动指定可访问的IP：

• 在WSL终端执行以下命令获取Windows主机的网关IP：

  cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
  

• 在项目根目录的.env文件中覆盖Xdebug配置：

  SAIL_XDEBUG_MODE=develop,debug,coverage
  SAIL_XDEBUG_CONFIG="client_host=192.168.x.x" # 替换为上一步获取的IP
  

• 重启容器：sail down && sail up -d

2. 检查端口占用与防火墙设置 #

• 端口占用检查：在Windows命令行执行以下命令，确认9003端口未被其他程序占用：

  netstat -ano | findstr :9003
  

  若有占用，可终止对应进程，或修改Xdebug端口（比如改为9004，同步更新VS Code的launch.json中的port字段）。
• 防火墙设置：确保Windows防火墙允许9003端口的入站连接，或暂时关闭防火墙测试是否能正常连接。

3. 避免自定义配置与Sail默认配置冲突 #

Sail已通过环境变量管理Xdebug配置，无需额外挂载自定义ext-xdebug.ini，否则可能导致配置冲突：

• 移除./docker/8.1/Dockerfile中的COPY ext-xdebug.ini /etc/php/8.1/cli/conf.d/ext-xdebug.ini指令；
• 删除自定义的ext-xdebug.ini文件；
• 重新构建容器：sail build --no-cache

4. 验证Xdebug配置是否生效 #

进入容器检查Xdebug参数是否正确加载：

sail exec laravel.test php -i | grep -A 20 "xdebug"

确认输出中xdebug.mode为debug,develop,coverage，xdebug.client_host为你指定的IP，xdebug.client_port为9003（或自定义端口）。

5. 确保调试触发方式正确 #

• 启动VS Code的调试监听（左侧调试面板选择"Listen for Xdebug"并点击启动按钮）；
• 在浏览器访问项目时，通过以下方式触发调试：
  • 在URL末尾添加参数：?XDEBUG_SESSION_START=VSCODE；
  • 安装浏览器Xdebug辅助扩展（如Xdebug Helper），开启调试模式。

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