Xdebug 3与PhpStorm连接超时问题排查（Docksal+Drupal环境）

针对你遇到的Xdebug连接超时问题，按以下步骤排查修复：

• 修正Xdebug端口配置
  Xdebug v3默认调试端口是9003，而非旧版的9000，错误日志显示当前用的是9000，这是核心问题：

  1. 编辑docksal-local.env，添加或修改：

     XDEBUG_CLIENT_PORT=9003
     

  2. 重启Docksal服务：fin project restart
  3. 在PhpStorm中进入Settings > Languages & Frameworks > PHP > Debug，确认Xdebug标签下的Debug port设置为9003，同时勾选Can accept external connections

• 验证宿主机IP可达性
  日志中的192.168.64.1是Docksal默认的宿主机IP，但部分网络环境下可能无法连通：

  1. 执行fin ip命令获取Docksal识别的宿主机IP
  2. 在docksal-local.env中手动指定该IP：

     XDEBUG_CLIENT_HOST=你获取到的宿主机IP
     

  3. 再次重启服务：fin project restart

• 确认调试监听状态
  确保PhpStorm右上角的调试监听按钮（电话图标）处于橙色激活状态，灰色表示未开启，点击切换即可。

• 验证Xdebug实际配置
  执行fin exec php -i | grep xdebug查看Xdebug的生效配置，确认xdebug.client_host和xdebug.client_port与你设置的一致，排除配置未加载的情况。

• 测试断点触发
  在Drupal入口文件index.php的第一行设置断点，访问站点，检查PhpStorm是否弹出调试连接提示，以此验证连接是否正常。

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