PHP接口调试前必须确认Xdebug三要素就绪：CLI和Web SAPI均启用Xdebug、请求带XDEBUG_SESSION_START参数、xdebug.client_host指向宿主机IP；用PhpStorm HTTP Client调试而非CLI模式。
PHP接口调试前必须确认Xdebug是否真正就绪
很多人以为装了Xdebug插件、配了xdebug.mode=debug就万事大吉，结果断点完全不触发。真实情况是：Xdebug 3+ 默认不监听远程请求，且必须同时满足三要素——本地PHP CLI用的配置里启用了Xdebug、Web服务器（如Apache/Nginx）使用的PHP SAPI也加载了同一套Xdebug、浏览器或curl请求中带了有效的XDEBUG_SESSION_START参数或cookie。
验证方法很简单：php -v看CLI是否显示Xdebug；访问phpinfo()页面搜索“xdebug.mode”，确认值为debug；再检查xdebug.client_host（不是remote_host！）是否指向你的宿主机IP（Docker环境常错设为localhost）。
用PhpStorm发起HTTP请求调试API，别手动写curl
直接在PhpStorm里右键.php文件 → Debug 'xxx.php'只适用于CLI脚本，对Web API无效。正确做法是用内置的HTTP Client——新建一个.http文件，写入类似这样的内容：
GET http://localhost:8000/api/users?id=123 User-Agent: PhpStorm XDEBUG_SESSION_START: PHPSTORM
然后把光标停在GET行，点左侧行号旁的绿色甲虫图标即可启动调试。关键点：
立即学习“PHP免费学习笔记（深入）”；
-
XDEBUG_SESSION_START这个header必须存在，值任意但需与PhpStorm设置里的Debug session ID一致（默认就是PHPSTORM） - URL必须能被当前Web服务器解析，建议用
php -S起个简易服务，避免Nginx/Apache配置干扰 - 如果接口依赖POST/JSON，用
POST方法 +Content-Type: application/json+ 原始JSON体，PhpStorm会自动注入Xdebug cookie
断点不命中？检查PHP脚本是否真的被Web服务器执行
常见假象：你在api/users.php打了断点，但请求/api/users?id=123却没停住。原因往往是路由被框架（Laravel、Slim等）接管，实际执行的是index.php，而你的断点在未被include的文件里。
解决路径：
- 先在入口文件（如
public/index.php）第一行打个断点，确认调试通道通不通 - 开启Xdebug的
xdebug.log，查看日志里有没有Connection to client successfully established - 如果是Composer自动加载的类，确保PhpStorm的
Include path已正确映射vendor目录，否则断点位置无法对齐源码 - 检查文件路径是否含中文或空格——Xdebug 3.2+对这类路径解析不稳定，建议全英文路径
调试时变量值显示__set_state或一堆protected字段
这是Xdebug默认不展开对象属性导致的视觉干扰，不是数据丢了。PhpStorm本身能读取完整结构，但需要你主动点开小箭头；更彻底的解法是在php.ini里加一句：xdebug.var_display_max_depth=10（默认是5），同时调高xdebug.var_display_max_children和xdebug.var_display_max_data。
注意：这些参数只影响调试器变量窗的显示，不影响性能。但如果设得过大（比如max_data=1000000），在调试大数组时可能卡死IDE。建议日常用max_depth=8、max_children=128、max_data=2048平衡可读性与响应速度。
复杂点在于：不同环境（CLI/Web）可能读取不同php.ini，务必确认你改的是Web SAPI加载的那个配置文件。
