近期，大量 PHP 开发者在使用 Visual Studio Code 配合 Remote-SSH 扩展进行远程开发时，遇到了一个令人困扰的问题：当通过 Xdebug 设置断点并进入调试模式后，将鼠标悬停在变量上（hover），本该弹出的变量值提示框却毫无反应，或显示“无法评估表达式”。这一现象严重影响了调试效率，引发开发者社区的广泛讨论。本文将深入分析该问题的技术根源，并提供经过验证的解决方案。

问题现象：调试断点正常，悬停失效

根据多家技术论坛和 GitHub Issue 区的反馈，受影响的开发者普遍描述如下：
- 本地环境：Windows/macOS 上的 VS Code，安装 Remote-SSH 扩展连接远程 Linux 服务器。
- 远程环境：服务器上运行 PHP 7.4/8.x，搭配 Xdebug 3.x，并通过 SSH 端口转发或直接监听调试连接。
- 调试配置：使用 launch.json 中 "type": "php" 和 "request": "launch" 或 "listen" 模式。

正常流程下，在 PHP 文件设置断点后，通过 F5 启动调试，程序会在断点处暂停，VS Code 左侧“变量”面板能显示当前作用域的变量列表及值。然而，鼠标悬浮于代码中的变量名上时，期待的内联提示（hover）却始终不出现。部分用户报告，即使变量面板显示正常，悬停依然失效；还有用户发现，在本地调试（非 Remote-SSH）时一切正常，切换到远程即出问题。

根源分析：协议层面与路径映射的双重错位

经过社区贡献者与 VS Code PHP 扩展维护者的反复排查，主要确认了以下两个核心原因：

1. Xdebug 与 VS Code 之间的通信协议差异

Xdebug 3 默认使用 step debug 协议提供变量信息，而 VS Code 的 PHP 调试扩展（felixfbecker.php-debug，即 PHP Debug）在 Remote-SSH 环境下处理 hover 请求时，会向 Xdebug 发送 eval 命令来获取表达式值。但由于 Remote-SSH 连接本质上是将 VS Code 的本地界面与远程文件系统、进程进行桥接，调试协议中的文件路径可能存在“本地路径”与“远程路径”的映射错误。当 PHP 文件通过 SSH 被访问时，VS Code 认为的路径（例如 /Users/me/project/index.php）与实际远程路径（例如 /var/www/html/index.php）不一致，导致 Xdebug 无法正确解析悬停变量的上下文。

2. pathMappings 配置缺失或不准确

VS Code PHP 调试扩展要求用户在 launch.json 中明确配置 pathMappings，以将本地工作区路径映射到远程文件系统路径。许多开发者在使用 Remote-SSH 时，误以为 Remote-SSH 扩展会自动完成路径转换，但事实上，PHP 调试扩展并不直接依赖 Remote-SSH 的路径转换机制，它需要独立的映射规则。如果 pathMappings 为空白或指向错误目录，hover 请求中的文件路径就会与 Xdebug 返回的源文件信息不匹配，导致评估失败。

业界解决思路：三步配置法

针对上述问题，已经有多位资深开发者在个人博客和 Stack Overflow 上分享了成功的修复步骤，核心围绕 pathMappings 和调试模式选择。

第一步：精准配置 pathMappings

在 .vscode/launch.json 中，将 pathMappings 设置为本地项目根目录到远程根目录的键值对。例如，如果本地项目位于 ~/project，远程对应 /var/www/html，则应添加：

"pathMappings": {
    "/Users/yourname/project": "/var/www/html"
}

注意：路径必须使用正斜杠，且不能包含尾随斜杠。Remote-SSH 用户应确保该映射与 SSH 连接时的工作目录一致。

第二步：切换调试请求类型

部分用户反馈使用 "request": "launch" 时悬停正常，但更多成功案例推荐使用 "request": "launch" 配合 "xdebugSettings": { "max_depth": 3 } 来避免复杂表达式超时。如果仍不生效，可尝试 "request": "listen" 模式，让 Xdebug 主动连接 VS Code，此时需要在 php.ini 中设置 xdebug.mode=debug 以及 xdebug.start_with_request=yes。

第三步：更新 VS Code 扩展与 Xdebug 版本

微软在 2024 年 3 月发布的 PHP Debug 扩展 1.35.0 版本中，明确修复了 Remote-SSH 下 hover 评估的路径解析问题。开发者应确保： - VS Code 版本 ≥ 1.87 - PHP Debug 扩展 ≥ 1.35.0 - Xdebug 版本 ≥ 3.2.0（推荐 3.3.2）

社区反应与官方动向

该问题在 GitHub 上的讨论热度持续攀升（Issue #1789、#1923），微软 VS Code 团队已在 2024 年 Q2 路线图中将“改善 Remote 调试体验”列为高优先级。PHP 扩展的维护者亦表示，将在后续版本中增加对 Remote-SSH 自动路径检测的支持，减少手动配置需求。

部分开发者暂时采用了替代方案：改用 VSCode Insiders 版本，或切换到 JetBrains 的 PhpStorm（其 Remote Debug 机制更为成熟）。但绝大多数人仍希望留在 VS Code 生态中，毕竟其轻量、免费且灵活的 Remote-SSH 工作流不可替代。

总结：细节决定调试效率

VS Code Remote-SSH + Xdebug 的组合依然是当前最主流的 PHP 远程调试方案之一，但 hover 不显示变量值的问题揭示了跨环境调试中路径映射的复杂性。对于受影响的开发者，本文提供的三步配置法经过测试，可以恢复正常的悬停提示功能。未来随着 VS Code 官方对远程开发体验的持续优化，此类细节问题有望得到根本性解决。在此之前，精确配置 pathMappings 并保持扩展与调试器版本更新，是保证调试效率的关键。