通过 SSH 隧道进行远程调试

本教程描述了如何使用 SSH 隧道（也称为 SSH 端口转发）在运行 Xdebug 的远程服务器和运行 PhpStorm 的开发机器之间建立安全连接。这对于在远程机器上调试代码非常有用，尤其是在中间有防火墙、NAT 路由器阻止直接连接，或 ISP 或网络基础设施不允许开发者机器接收传入的 TCP 连接时。

当远程服务器可以直接连接到开发者机器时（例如，使用 Vagrant 机器），可能不需要 SSH 隧道。

先决条件

1. 调试器已在远程服务器上设置

在开始调试之前，请确保您已在运行 PHP 应用程序的 Web 服务器上正确安装并配置了调试引擎。

PhpStorm 支持使用两种最流行的工具进行调试： Xdebug 和 Zend Debugger。这些工具不能同时使用，因为它们会相互阻碍。为避免此问题，您需要按照配置 Xdebug 和配置 Zend Debugger 中的描述更新相关 PHP 解释器的 php.ini 文件。

例如，对于 Xdebug，请确保在服务器上的 php.ini 中指定了以下设置：

                        [xdebug]
                        zend_extension="<path to xdebug extension>"
                        xdebug.mode=debug
                        xdebug.client_host=127.0.0.1
                        xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"
                    
     

                        [xdebug]
                        zend_extension="<path to xdebug extension>"
                        xdebug.remote_enable=1
                        xdebug.remote_host=127.0.0.1
                        xdebug.remote_port="<the port (9000 by default) to which Xdebug connects>"
                    
     

zend_extension ：指示应使用 Xdebug 调试引擎的设置。设置为 xdebug 或使用 xdebug.so 文件的完整路径，例如 /usr/lib/php/20190902/xdebug.so。
xdebug.mode ：控制启用哪些 Xdebug 功能的设置。设置为 debug 以进行调试。
xdebug.client_host ：PhpStorm 运行并监听来自 Xdebug 的传入连接的 IP 地址或主机名。
xdebug.client_port ：Xdebug 尝试连接到运行 PhpStorm 的主机上的端口。默认端口是 9003。

2. PhpStorm 中已启用监听传入的调试器连接

在 PhpStorm 中，通过执行以下任一操作启用监听传入的调试连接：

单击工具栏/状态栏上的。
在主菜单中选择运行 | 开始侦听PHP 调试连接。

这确保了当在 Web 服务器上启动调试会话时，PhpStorm 会做出反应并自动打开调试工具窗口。在开始调试会话之前，请确保已设置断点或在 Debug 对话框的设置页面上启用了在PHP 脚本中的第一行中断选项 Ctrl+Alt+S。

设置 SSH 隧道

当您开始调试会话时，是 Xdebug 从远程服务器发起到开发者机器上 PhpStorm 监听的端口的 TCP 连接。

SSH 端口转发的理念是创建一个远程服务器上的“虚拟”TCP 端口，将其流量发送到开发者机器上的 TCP 端口，通过 SSH 隧道传输流量。

设置 SSH 隧道

要设置 SSH 端口转发，请在命令行上运行以下 ssh 命令：

ssh -R 9003:localhost:9003 username@hostname

ssh -R 9000:localhost:9000 username@hostname

ssh -R 10137:localhost:10137 username@hostname

9003: 在 9003:localhost:9003 中是 SSH 服务器（转发主机）上的端口，从该端口 Xdebug 连接将被转发到 localhost。
localhost:9003 在 9003:localhost:9003 中是 SSH 客户端（运行 PhpStorm 的机器）的 IP 地址及其上的端口，到该端口 Xdebug 连接将被转发。 localhost 本质上是您运行此 ssh 命令的机器。
username@hostname 是 SSH 服务器（转发主机）的地址以及进行 SSH 身份验证所需的用户名。

要检查 SSH 隧道是否已成功设置，请通过使用 PhpStorm 书签、浏览器调试扩展或使用 PhpStorm 调试 PHP CLI 脚本中概述的技术，在远程服务器上启动调试会话。一旦 PhpStorm 检测到传入连接，它会显示来自 Xdebug 的传入连接对话框，提示您接受连接。

有关 PhpStorm 中调试过程的更多信息，请参阅零配置调试和检查挂起的程序。

使用远程 PHP 解释器或通过 SSH 隧道调试 PHP CLI 脚本

当远程 PHP 解释器正确配置后，可以创建一个运行/调试配置，利用远程 PHP 解释器进行调试。

当 SSH 隧道已启动并运行时，我们还可以调试 PHP CLI 脚本。由于调试器运行在远程机器上，可以通过使用 PHP 命令行开关或环境变量（在远程机器上）启动 CLI 调试会话。此工作流程并非官方推荐的调试方式，但在某些需要从远程服务器端建立调试会话的情况下可能会有用。

故障排查

调试器从未连接或拒绝连接

当调试器从未连接或拒绝连接时，请检查以下内容：

确保 Xdebug 配置为连接到 127.0.0.1 和端口 9000（适用于 Xdebug 2）或端口 9003（适用于 Xdebug 3）。
使用 Zend Debugger 时，请确保 PhpStorm 书签或浏览器调试扩展配置为连接到 127.0.0.1 。
确保在设置 SSH 隧道之前，PhpStorm 正在监听传入的调试器连接。
当机器重新启动或连接丢失时，必须重新建立 SSH 隧道。

远程文件路径未映射到项目中的文件路径

在某些情况下，调试器可以连接，但我们会收到错误消息，表明未定义远程文件和项目文件之间的映射。这意味着 PhpStorm 无法确定与正在调试的文件对应的本地文件。

我们可以通过单击点击以设置路径映射并提供必要的路径映射来解决此问题。此外，我们可以使用连接到 Web 服务器中概述的技术配置这些映射。

最后修改日期： 2025年 9月 26日