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
直接对着.php文件右键选择Debug 'xxx.php'，那只对CLI脚本管用，调试Web API接口完全是另一回事。正确且高效的做法，是活用PhpStorm内置的HTTP Client工具。具体怎么操作？新建一个.http文件，把请求内容写进去，比如：
GET https://localhost:8000/api/users?id=123 User-Agent: PhpStorm XDEBUG_SESSION_START: PHPSTORM
接下来，把光标停在GET那一行，点击左侧行号旁边的绿色甲虫图标，调试会话就启动了。这里有三个关键点需要把握：
立即学习“PHP免费学习笔记（深入）”；
XDEBUG_SESSION_START这个请求头必须存在，值可以任意，但需要和PhpStorm设置里的Debug session ID保持一致（默认就是PHPSTORM）- 请求的URL必须确保能被当前的Web服务器正确解析。为了避免复杂的Nginx或Apache配置带来干扰，一个实用的建议是直接用
php -S命令启动一个内置的简易开发服务器。 - 如果调试的是POST接口或者需要发送JSON数据，方法也很简单：改用
POST方法，加上Content-Type: application/json头，然后写上原始的JSON请求体即可，PhpStorm会自动帮你注入Xdebug所需的Cookie。
断点不命中？检查PHP脚本是否真的被Web服务器执行
一个常见的调试假象是：你在api/users.php文件里打好了断点，但访问/api/users?id=123时，程序却毫无停顿地跑过去了。这多半是因为项目使用了框架（比如Lara vel、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字段
调试时看到变量窗口里显示__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所加载的那一个配置文件，否则配置可能不生效。
