为什么必须用 SSH 隧道而不是直接连 Xdebug 端口
因为你的本地机器和远程服务器之间存在 NAT、防火墙或跨公网限制，xdebug.client_host 直接填你本机 IP 会失败——远程服务器根本 ping 不通你，也发不出 DBGP 包。SSH 隧道本质是把远程的 9003（或你设的调试端口）“悄悄搬”到你本地的 127.0.0.1:9003，让 PhpStorm 认为调试器就在本机。
常见错误现象：Connection refused、PhpStorm 一直监听但无反应、浏览器请求后断点不命中。
- 别在远程服务器上开防火墙放行
9003—— 这等于暴露调试接口，不安全 - 别在 PhpStorm 的
PHP > Servers里把 Host 填成远程 IP 并指望它直连 Xdebug —— 这是纯内网场景才有效的配置 - SSH 隧道命令中
localhost指的是「远程服务器视角的 localhost」，不是你本地机器
ssh -L 命令怎么写才不翻车
在你本地终端执行（不是远程服务器上）：
ssh -L 9003:127.0.0.1:9003 user@remote-server-ip -p 22
关键点：
-
9003:是你本地监听的端口，必须和 PhpStorm 的Debug port（Settings > PHP > Debug）一致 -
127.0.0.1:9003是远程服务器上 Xdebug 实际监听的目标 —— 它必须是127.0.0.1，不是0.0.0.0或外网 IP；否则 SSH 无法绑定转发 - 如果远程服务器 SSH 端口不是
22，必须显式加-p xxx - 连接保持住别关终端，否则隧道中断；可加
-N -f后台运行（但首次调试建议先不加，方便看报错）
PhpStorm 里哪些设置必须对齐隧道逻辑
Settings > PHP > Servers 中的配置，和隧道是解耦的 —— 它只管 HTTP 请求路由，不管调试连接。真正决定调试走哪条路的是以下两处：
-
Settings > PHP > Debug > Debug port：必须是9003（或你隧道本地端口），不能是9001或其他 -
Settings > PHP > Debug > DBGp Proxy：这里 不要填 —— 只有启用 DBGP Proxy 模式（即远程服务器主动连你）才需要，而你走的是 SSH 隧道 + Xdebug 主动连 localhost，Proxy 设置留空 -
xdebug.client_host在远程php.ini里必须是127.0.0.1，不是你本机 IP；xdebug.client_port必须和隧道远端端口一致（即9003）
验证方式：在远程服务器上跑 curl http://127.0.0.1:9003 应该返回 Connection refused（说明 Xdebug 没开 HTTP 服务，正常）；但 ss -tln | grep 9003 应该看到 127.0.0.1:9003 处于 LISTEN 状态（说明 Xdebug 已加载并监听）。
路径映射错一个字符就断点失效
PhpStorm 通过文件路径匹配来定位断点位置。远程服务器上代码实际路径是 /var/www/html/index.php，而你本地项目根目录是 /Users/me/project，这两者必须在 Settings > PHP > Servers 的 Use path mappings 下严格对应：
- 左边填本地路径：
/Users/me/project - 右边填远程路径：
/var/www/html - 不能多斜杠、不能少斜杠、大小写敏感（Linux 下尤其注意）
- 如果远程用的是 symlink，确保映射的是真实路径，不是软链路径
- 改完映射后，务必点击右下角
Validate—— 它会尝试从远程读取一个测试文件，失败就说明路径不通或权限不对
最容易被忽略的复杂点：Xdebug 3.x 默认只在 CLI 模式下加载扩展，Web 请求（如 Apache/FPM）可能走的是另一套 php.ini。务必确认 /etc/php/8.2/fpm/conf.d/20-xdebug.ini（或对应 FPM 版本路径）里已启用，且 systemctl restart php8.2-fpm 生效。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
