Xdebug连接成功却不触发断点，PHP远程调试问题求助

局域网内有一台运行PHP应用的服务器（地址192.168.0.21），需在本地Visual Studio Code中调试服务器上的脚本，已完成以下操作：

• 通过SSH直接编辑服务器文件
• VS Code安装Xdebug扩展
• 服务器安装Xdebug，phpinfo()已检测到组件

修改端口后，telnet验证服务器可正常连接本地机器，但调试时既不触发断点也无任何响应，需排查是否遗漏关键配置。

已尝试操作：

• 多次重启Apache服务
• 参照教程设置本地路径映射（未理解原理）
• 关闭防火墙

相关配置信息 #

VS Code调试配置 #

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

Xdebug日志 #

[207613] Log opened at 2024-06-17 08:39:12.333867
[207613] [Step Debug] INFO: Connecting to configured address/port: 192.168.0.138:7680.
[207613] [Step Debug] INFO: Connected to debugging client: 192.168.0.138:7680 (through xdebug.client_host/xdebug.client_port). :-)
[207613] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="dbgp://stdin" language="PHP" xdebug:language_version="8.1.2-1ubuntu2.14" protocol_version>

[207613] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" status="stopping" reason="ok"></response>

服务器Xdebug配置 #

[xdebug]
zend_extension=/usr/lib/php/20210902/xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=192.168.0.138
xdebug.client_port=7680
xdebug.log = /var/log/xdebug.log
xdebug.log_level=7

1. 修正路径映射配置
   从Xdebug日志看，连接已建立但立即停止，核心原因是本地与服务器的文件路径不匹配，导致VS Code无法将本地断点关联到服务器脚本。需在VS Code调试配置中添加pathMappings字段，将服务器项目根目录映射到本地工作区路径：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 7680,
            "log": true,
            "pathMappings": {
                "/服务器项目根目录绝对路径": "${workspaceFolder}"
            }
        }
    ]
}

示例：若服务器项目位于/var/www/html/myapp，本地VS Code工作区为该SSH目录，则配置为"/var/www/html/myapp": "${workspaceFolder}"。

2. 确认调试触发方式

• 若调试Web请求：需确保浏览器携带Xdebug触发Cookie，可使用Xdebug官方浏览器插件一键添加。
• 若调试CLI脚本：执行脚本时需确保环境变量继承Xdebug配置，或手动指定XDEBUG_SESSION=VSCODE。

3. 验证断点有效性

• 断点需设置在可执行代码行（避免空行、注释行、函数/类定义行）。
• 确认VS Code中断点显示为实心红点（空心表示断点未被识别，需检查路径映射或文件关联）。

4. 查看VS Code调试日志
   配置中已开启log: true，查看.vscode/debug.log文件，若存在"could not find local file for..."等报错，需根据提示调整路径映射规则。

5. 优化Xdebug配置
   可补充以下配置项提升调试稳定性：

xdebug.discover_client_host=0  # 禁用自动发现，强制使用指定的client_host
xdebug.idekey=VSCODE  # 统一IDE标识，与VS Code扩展匹配

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