PHPStorm通过SSH隧道实现公网远程调试Xdebug配置-php教程-PHP中文网

必须使用ssh反向隧道（-r）实现xdebug远程调试，因公网无固定ip且入向端口被屏蔽；需配置gatewayports yes、xdebug.client_host=127.0.0.1，并在phpstorm中启用dbgp proxy模式。

phpstorm通过ssh隧道实现公网远程调试xdebug配置

能用，但必须绕开公网直连限制，核心是让远程服务器“反向连回”你的本地IDE——SSH隧道就是干这个的，不是可选项，是必选项。

为什么不能直接配置 `xdebug.remote_host` 为你的公网IP

因为绝大多数家用/企业宽带没有固定公网IP，即使有，运营商也默认屏蔽入向连接（尤其是 9000–9003 这类调试端口）。xdebug.remote_connect_back=1 在公网环境基本失效：它依赖 HTTP 请求头里的 X-Forwarded-For 或 Remote-Addr，而云服务器转发过来的请求源 IP 往往是 Nginx/LB 的内网地址，不是你的真实出口 IP。

现象：xdebug 日志里反复出现 Failed to connect to host 或静默无响应
验证方法：在远程服务器上执行 telnet your_public_ip 9001，大概率超时或拒绝连接
结论：这条路在公网场景下不可靠，别浪费时间调 remote_connect_back

`ssh -R` 远程端口转发的正确写法

关键不是“本地监听”，而是让远程服务器主动把调试流量推到你本地的 IDE。用 -R（Remote port forwarding）而非 -L（Local）。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

命令示例：ssh -N -R 9001:localhost:9001 user@your-server-ip
-N 表示不执行远程命令，只建隧道（避免黑屏卡住）
-R 9001:localhost:9001 含义：远程服务器的 9001 端口 → 转发到你本地机器的 localhost:9001
必须提前在远程服务器的 /etc/ssh/sshd_config 中设置 GatewayPorts yes，否则 -R 只绑定 127.0.0.1，Xdebug 连不上
启动后，在远程服务器上执行 ss -tlnp | grep :9001，应看到 *:9001 而非 127.0.0.1:9001

PHPStorm 里对应的关键配置项

IDE 不再试图“连过去”，而是坐等远程服务器把连接送进来。配置重心从 “Server” 切换到 “DBGP Proxy”。

Settings > PHP > Servers：Host 填你实际访问网站的域名（如 test.example.com），Port 填 Web 服务端口（如 80 或 443），勾选 Use path mappings 并严格对齐远程项目路径（如 /var/www/html → /Users/me/project）
Settings > PHP > Debug > DBGp Proxy：IDE key 必须和 xdebug.idekey 一致（如 PHPSTORM），Host 填 localhost，Port 填你本地监听的端口（如 9001）
不要在 Run > Edit Configurations 里新建 “PHP Remote Debug” —— 那是给 DBGP Proxy 模式用的，你走的是纯 SSH 隧道，不需要它

远程服务器上 Xdebug 的最小可用配置

精简掉所有依赖网络探测的参数，只留最稳的组合：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9001
xdebug.idekey=PHPSTORM
xdebug.log=/tmp/xdebug.log

xdebug.mode=debug 替代旧版的 xdebug.remote_enable（Xdebug 3+ 必须用）
xdebug.client_host=127.0.0.1 是重点：Xdebug 认为调试器就在本机（其实是通过 SSH 隧道映射过去的），彻底规避公网寻址问题
xdebug.log 打开后，一旦断点不触发，立刻去远程服务器查 /tmp/xdebug.log，里面会明确写 “Connecting to 127.0.0.1:9001…” 和成功/失败结果
确认 PHP 重启生效：systemctl restart php-fpm 或 service apache2 restart