PhpStorm远程调试必须SSH与Xdebug协同：先通SSH连接和Deployment，再配Xdebug 3.x参数（xdebug.mode=debug、client_host填本地IP、client_port=9003），并严格对齐路径映射、SAPI环境及IDE监听端口。
PhpStorm 远程调试必须走 SSH + Xdebug 组合，只配 Deployment 或只改 php.ini 都不能断点生效。
SSH 连接和 Deployment 配置必须先跑通
远程调试依赖底层连接通道，如果 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 默认端口），否则本地监听收不到回调
Xdebug 配置要严格匹配 PhpStorm 版本和模式
PhpStorm 2023.3+ 默认用 Xdebug 3.x 协议，xdebug.remote_* 类旧参数已废弃，硬写进去反而让扩展加载失败。
- 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
PhpStorm 解释器和 Debug 监听必须对齐
很多人配完发现断点灰了，其实是解释器没识别到 Xdebug，或监听没开对端口。
立即学习“PHP免费学习笔记（深入）”；
- 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
最易忽略的是路径映射和 SAPI 差异——Xdebug 是附着在具体 PHP 进程上的，CLI 配好了，Web 服务未必跟着动；本地文件路径一变，断点就成“幽灵断点”，看着亮，实际不进。
