Xdebug在Chrome中无法触发断点（IDE为VSCode）

问题场景 #

本地环境配置Xdebug 3.1.5，PHP@7.2，VSCode作为IDE，Chrome安装Xdebug Helper扩展。终端执行php index.php可正常触发断点，但通过Chrome访问该文件时无法暂停。相关配置如下：

ext-xdebug.ini：

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.idekey=vsc
xdebug.start_with_request = yes
xdebug.discover_client_host = 1
xdebug.log=/tmp/xdebug.log
xdebug.log_level=10

VSCode launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
        },
    ]
}

VSCode PHP Debug插件IDE Key设置为vsc，Xdebug Helper的IDE Key也设置为vsc。

排查与解决步骤 #

• 确认Web服务器的PHP加载了Xdebug配置
  终端PHP CLI和Web服务器（Apache/Nginx）使用的是不同的php.ini文件。创建info.php文件，内容为<?php phpinfo(); ?>，通过Chrome访问后搜索Xdebug关键字：

  • 若找不到Xdebug相关信息，说明Web服务器的PHP未加载ext-xdebug.ini，需将Xdebug配置添加到Web服务器对应的php.ini中，或确保ext-xdebug.ini被正确引入。
  • 检查xdebug.mode是否为debug，xdebug.idekey是否为vsc，xdebug.client_port是否为9003（Xdebug3默认端口为9003，未设置则默认生效）。

• 强制设置客户端主机地址
  xdebug.discover_client_host=1在部分本地环境中可能错误识别客户端IP（比如识别为Web服务器内部IP），导致Xdebug无法连接VSCode。修改ext-xdebug.ini：

  xdebug.discover_client_host = 0
  xdebug.client_host = 127.0.0.1
  

  修改后必须重启Web服务器，再尝试触发断点。

• 确保Xdebug Helper已激活
  打开Chrome，点击地址栏右侧的Xdebug Helper图标，确认图标为绿色（激活状态）。若为灰色，切换到Debug模式，确保发送XDEBUG_SESSION=vsc的Cookie。

• 验证端口监听与连通性

  1. 启动VSCode的Xdebug监听：点击左侧运行图标，选择Listen for Xdebug启动，控制台应显示"Listening for Xdebug on port 9003"。
  2. 检查端口占用：执行终端命令lsof -i :9003，确认只有VSCode进程在监听该端口。若有其他进程占用，关闭对应程序或同步修改Xdebug端口与launch.json的port参数。

• 通过日志定位问题
  访问网页触发请求后，查看/tmp/xdebug.log文件：

  • 搜索Connecting to configured address/port，确认Xdebug尝试连接的IP和端口为127.0.0.1:9003。
  • 若出现Could not connect to client，检查防火墙是否阻止9003端口，或VSCode的监听状态是否正常。

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