VSCode远程PHP调试：pathMapping不支持ssh://路径问题求助

设置pathMapping后，VSCode错误地将ssh://路径附加到Windows本地VSCode安装路径中，弹出“无法打开编辑器，文件未找到”提示，错误路径示例：C:\Users\me\AppData\Local\Programs\Microsoft VS Code\ssh:\remote-ssh-con\server\path\htdocs\index.php。由于PHP代码所在的OS400系统不支持Remote SSH，当前使用SSH FS进行远程文件访问。

现有配置 #

php.ini的Xdebug配置 #

zend_extension=xdebug
xdebug.mode=develop,debug
xdebug.discover_client_host=1
xdebug.client_port=9003
xdebug.log=/server/path/logs/xdebug.log
xdebug.log_level=10

SSH FS配置 #

{
    "name": "remote-ssh-con",
    "host": "***",
    "root": "/server/path/htdocs",
    "username": "***",
    "password": true
}

调试launch.json配置 #

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "stopOnEntry": true,
    "pathMappings": {
        "/server/path/htdocs" : "ssh://remote-ssh-con/server/path/htdocs"
    }
}

Xdebug日志 #

[90200] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///server/path/htdocs/index.php" language="PHP" xdebug:language_version="8.1.27" protocol_version="1.0" appid="90200" idekey="mykey"><engine version="3.3.0"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2023 by Derick Rethans]]></copyright></init>

[90200] [Step Debug] <- breakpoint_list -i 1
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="breakpoint_list" transaction_id="1"></response>

[90200] [Step Debug] <- breakpoint_list -i 2
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="breakpoint_list" transaction_id="2"></response>

[90200] [Step Debug] <- breakpoint_list -i 3
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="breakpoint_list" transaction_id="3"></response>

[90200] [Step Debug] <- breakpoint_set -i 4 -t line -f file:///server/path/htdocs/index.php -n 4
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="breakpoint_set" transaction_id="4" id="902000010"></response>

[90200] [Step Debug] <- breakpoint_set -i 5 -t exception -x Error
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="breakpoint_set" transaction_id="5" id="902000011"></response>

[90200] [Step Debug] <- breakpoint_set -i 6 -t exception -x Exception
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="breakpoint_set" transaction_id="6" id="902000012"></response>

[90200] [Step Debug] <- step_into -i 7
[90200] [Step Debug] DEBUG: Setting 'has_line_breakpoints on {main} (/server/path/htdocs/index.php:0)
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="step_into" transaction_id="7" status="break" reason="ok"><xdebug:message filename="file:///server/path/htdocs/index.php" lineno="4"></xdebug:message></response>

[90200] [Step Debug] <- stack_get -i 8
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="stack_get" transaction_id="8"><stack where="{main}" level="0" type="file" filename="file:///server/path/htdocs/index.php" lineno="4"></stack></response>

[90200] [Step Debug] <- context_names -i 9 -d 0
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="context_names" transaction_id="9"><context name="Locals" id="0"></context><context name="Superglobals" id="1"></context><context name="User defined constants" id="2"></context></response>

[90200] [Step Debug] <- context_get -i 10 -d 0 -c 0
[90200] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="context_get" transaction_id="10" context="0"><property name="$FWREQ" fullname="$FWREQ" type="uninitialized"></property><property name="$action" fullname="$action" type="uninitialized"></property><property name="$actionfile" fullname="$actionfile" type="uninitialized"></property><property name="$conn" fullname="$conn" type="uninitialized"></property><property name="$fwURL" fullname="$fwURL" type="uninitialized"></property><property name="$msg" fullname="$msg" type="uninitialized"></property><property name="$outputFormat" fullname="$outputFormat" type="uninitialized"></property><property name="$sessionOK" fullname="$sessionOK" type="uninitialized"></property><property name="$subaction" fullname="$subaction" type="uninitialized"></property><property name="$user" fullname="$user" type="uninitialized"></property></response>

解决方案 #

问题根源是VSCode PHP调试插件不支持直接将ssh://协议路径作为pathMappings的映射值，需替换为SSH FS挂载的工作区相对路径或虚拟文件系统标识：

方式1：使用工作区相对路径 #

如果SSH FS挂载的/server/path/htdocs是当前VSCode工作区的根目录，直接映射到.：

"pathMappings": {
    "/server/path/htdocs": "."
}

若挂载目录是工作区的子目录（比如./remote-htdocs），则映射到对应子路径：

"pathMappings": {
    "/server/path/htdocs": "./remote-htdocs"
}

方式2：使用SSH FS虚拟路径标识 #

利用SSH FS配置中的name字段（此处为remote-ssh-con），使用虚拟路径格式${remote-ssh-con:/}：

"pathMappings": {
    "/server/path/htdocs": "${remote-ssh-con:/}"
}

额外注意事项 #

• 若调试连接不稳定，可将xdebug.discover_client_host=1改为指定Windows本地IP：xdebug.client_host=你的本地IP地址
• 确保SSH FS的root路径与Xdebug日志中的文件绝对路径（/server/path/htdocs）完全一致，路径大小写敏感，避免拼写错误

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