在PHP项目开发中，当项目部署在公网服务器上时，本地直接调试远程代码往往受网络限制，直接开放Xdebug调试端口还存在安全隐患。通过SSH隧道的方式，可以安全地将远程服务器的Xdebug端口映射到本地，配合PHPStorm完成远程调试配置。
一、服务器Xdebug环境配置
首先需要在公网服务器上安装并配置Xdebug扩展，不同PHP版本的Xdebug安装方式略有差异，这里以PHP7.4为例。
1. 安装Xdebug
可以通过pecl命令直接安装：
# 安装Xdebug pecl install xdebug # 配置php.ini添加扩展 echo "zend_extension=xdebug.so" >> /etc/php/7.4/cli/php.ini echo "zend_extension=xdebug.so" >> /etc/php/7.4/fpm/php.ini
2. 配置Xdebug参数
在php.ini中添加以下Xdebug配置项：
[xdebug] ; 开启远程调试 xdebug.mode=debug ; 调试客户端地址，这里填127.0.0.1即可，后续通过隧道映射 xdebug.client_host=127.0.0.1 ; 调试端口，默认9003，可自定义 xdebug.client_port=9003 ; 自动触发调试 xdebug.start_with_request=yes ; 日志路径，方便排查问题 xdebug.log=/tmp/xdebug.log
配置完成后重启PHP服务：
systemctl restart php7.4-fpm
二、建立SSH隧道
SSH隧道的作用是将远程服务器的9003端口映射到本地9003端口，这样PHPStorm连接本地9003端口就相当于连接远程服务器的调试端口。
在本地终端执行以下命令建立隧道：
# 格式：ssh -R 远程端口:本地地址:本地端口 远程服务器用户名@远程服务器IP # 这里是将远程服务器的9003端口映射到本地127.0.0.1的9003端口 ssh -R 9003:127.0.0.1:9003 root@192.168.0.1
如果需要隧道在后台保持运行，可以添加-N -f参数：
ssh -N -f -R 9003:127.0.0.1:9003 root@192.168.0.1
三、PHPStorm调试配置
1. 配置Deployment
打开PHPStorm，进入File - Settings - Build, Execution, Deployment - Deployment，点击加号选择SFTP类型。
配置连接信息：
- Type选择SFTP
- Host填写远程服务器IP，比如192.168.0.1
- Port填写SSH端口，默认22
- Username填写远程服务器登录用户名
- Auth type选择密码或者密钥认证
- Root path填写远程项目的根目录
切换到Mappings标签，配置本地项目路径和远程项目路径的映射关系，确保本地文件和远程文件路径对应。
2. 配置PHP解释器
进入Settings - PHP，点击CLI Interpreter右侧的省略号，添加远程解释器。
选择Deployment configuration，选择刚才配置的Deployment，PHPStorm会自动检测远程服务器的PHP版本和Xdebug信息。
3. 配置Debug端口
进入Settings - PHP - Debug，在Debug port处填写9003，和服务器Xdebug配置的端口保持一致，勾选Can accept external connections。
4. 开启调试监听
点击PHPStorm右上角的电话图标，开启调试监听，此时PHPStorm会监听本地9003端口。
四、验证调试功能
在本地项目中设置断点，然后通过浏览器或者接口工具访问远程服务器的项目接口，触发代码执行后，PHPStorm会自动捕获调试请求，进入断点调试模式，可以查看变量值、调用栈等信息。
如果遇到调试不生效的情况，可以先查看远程服务器的/tmp/xdebug.log日志，排查Xdebug是否成功发起调试连接，再检查SSH隧道是否正常建立，本地端口是否被占用。
常见问题排查
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 隧道建立失败 | SSH端口未开放、服务器登录信息错误 | 检查服务器SSH端口是否放行，确认登录用户名密码正确 |
| Xdebug无日志输出 | Xdebug配置未生效、日志路径无写入权限 | 执行php -i | grep xdebug查看配置是否加载，修改日志路径权限 |
| PHPStorm无调试响应 | 端口不一致、未开启监听、隧道未映射成功 | 确认PHPStorm和Xdebug端口一致，开启监听，检查隧道状态 |