PhpStorm远程调试SSH配置步骤（干货分享）-phpstorm-PHP中文网

phpstorm远程调试必须ssh与xdebug协同：先通ssh连接和deployment，再配xdebug 3.x参数（xdebug.mode=debug、client_host填本地ip、client_port=9003），并严格对齐路径映射、sapi环境及ide监听端口。

phpstorm远程调试ssh配置步骤（干货分享）

PhpStorm 远程调试必须走 SSH + Xdebug 组合，只配 Deployment 或只改 php.ini 都不能断点生效。

远程调试依赖底层连接通道，如果 Deployment 测试失败，Xdebug 根本连不上 IDE。常见卡点：

Host 字段别写 ssh://xxx —— PhpStorm 会直接报 “Connection refused”
密钥认证必须用 PEM 格式私钥；OpenSSH 9.0+ 默认生成的 id_rsa 是新格式，老版 PhpStorm 不认，得转：ssh-keygen -p -m PEM -f ~/.ssh/id_rsa
Root path 填绝对路径，比如 /var/www/html；填 ~ 或留空会导致映射错乱，上传后文件出现在家目录而非 Web 根目录
确认服务器防火墙放行了 22（SSH）和 9003（Xdebug 默认端口），否则本地监听收不到回调

PhpStorm 2023.3+ 默认用 Xdebug 3.x 协议，xdebug.remote_* 类旧参数已废弃，硬写进去反而让扩展加载失败。

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

下载

php.ini 中必须启用： zend_extension=xdebug.so（路径用 php --ini 查准）
关键三行（Xdebug 3.1+）：xdebug.mode=debug、xdebug.start_with_request=yes、xdebug.client_host=192.168.1.100（填你本地机器的真实内网 IP，不是 localhost 或 127.0.0.1）
别漏掉 xdebug.client_port=9003 —— PhpStorm 2022.3 起默认监听 9003，不是旧版的 9000
验证是否生效：在服务器跑 php -m | grep xdebug，再执行 php -i | grep "xdebug.mode" 确认值是 debug

很多人配完发现断点灰了，其实是解释器没识别到 Xdebug，或监听没开对端口。

PHP CLI Interpreter 必须指向远程 PHP，并手动指定 Configuration file 路径（用 php --ini 输出的 Loaded Configuration File）
IDE 右上角电话图标（Start Listening for PHP Debug Connections）要点亮，且状态栏显示 “Debug listening…”
Web 服务请求触发调试时，URL 必须带 XDEBUG_SESSION_START=PHPSTORM 参数，或者浏览器装 Xdebug Helper 插件并激活
如果用 Nginx/Apache，确保 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 正确，否则 PhpStorm 找不到对应文件断点

不是配置漏了，而是运行环境和路径映射没对上。

本地项目路径和远程 Root path 的映射必须 1:1 —— 比如本地是 /Users/me/project，远程是 /var/www/html，就得在 Deployment → Mappings 里把 Project root 映射到 /var/www/html，否则断点文件找不到
CLI 和 Web 请求走的是不同 PHP SAPI，php -v 正常不代表 php-fpm 加载了 Xdebug；检查 php-fpm.d/www.conf 是否有 php_admin_value[extension] 开启 xdebug.so
容器环境（Docker）下，xdebug.client_host 得填宿主机 IP，不是 host.docker.internal（某些 Linux 发行版不支持该 DNS）
IDE 缓存可能干扰：试过所有步骤仍无效，可尝试 File → Invalidate Caches and Restart → Just Restart