断点无效的根本原因是Xdebug未正确启用或PhpStorm调试配置未连通；需检查xdebug.mode、服务器路径映射、端口一致性和网络设置，并确认xdebug_info()与IDE Key匹配。
断点打不上去，代码根本没停住
常见现象是点了行号左边的灰色区域，看起来加了红点，但运行后完全不中断。根本原因通常是 php 脚本没走 xdebug 或 php debug 扩展路径，或者 phpstorm 的调试配置压根没连上。
- 确认
xdebug.mode是debug（PHP 8.1+）或xdebug.remote_enable=1（旧版），且xdebug.start_with_request=yes（避免手动加?XDEBUG_SESSION_START=1） - PhpStorm 中检查
Settings > PHP > Servers是否配了对应域名/端口，并勾选Use path mappings，本地路径和服务器路径必须严格一致（比如/var/www/html对应D:\project\src） - 别用 CLI 运行脚本调试——默认不触发 Web 调试通道；改用浏览器访问 URL，或用
php -dxdebug.mode=debug script.php强制启用（仅限 CLI 场景）
单步执行时跳进 Xdebug 源码或 vendor 里出不来
这不是 PhpStorm 故障，是默认“Step Into”会钻进所有函数调用，包括扩展内部和 Composer 包。你真正想看的是自己写的逻辑，不是 XdebugBaseFilter 的第 7 行。
- 优先用
Step Over（F8）逐行执行当前作用域，不进函数体 - 需要进某个自定义函数时，把光标停在函数名上再按
Step Into（F7），比盲目 F7 更可控 - 在
Settings > PHP > Debug > Stepping中勾选Ignore external libraries，能过滤掉大部分 vendor 和系统扩展 - 临时不想进某函数？右键该行 →
Force Step Over，它会把整个调用当黑盒跳过
变量值显示 undefined 或始终是旧值
常见于数组、对象、闭包等复杂类型，尤其在循环或引用传递后。不是数据丢了，是 PhpStorm 默认只展开一层，或变量本身生命周期已结束。
- 变量窗口里点小箭头展开层级，或右键变量 →
View Value看完整结构（支持 JSON 格式化） - 如果值是
&$ref引用，在变量名旁会出现→符号，点开才能看到真实指向的内容 - 循环中变量被复用？把鼠标悬停在变量上，PhpStorm 会显示历史快照（Hover tooltip），比底部 Variables 面板更及时
- 确保没勾选
Settings > PHP > Debug > Skip files outside project，否则 include 的文件里变量可能不被追踪
调试器连上了但 Xdebug 报错 Connection refused
这是端口通信失败，不是代码问题。PhpStorm 监听的端口和 Xdebug 尝试连接的目标端口对不上，或者防火墙/IDE 设置拦住了。
- 检查
Settings > PHP > Debug > Xdebug下的Debug port（默认 9003），必须和 php.ini 里的xdebug.client_port=9003完全一致 - macOS / Linux 上注意：Docker 容器里跑 PHP，
xdebug.client_host不能写localhost，得填宿主机 IP（如172.17.0.1）或用host.docker.internal - Windows 用户若用 WSL2，
xdebug.client_host填localhost通常无效，得用cat /etc/resolv.conf | grep nameserver | awk '{print $2}'查 WSL2 网关地址 - 临时验证端口通不通：终端执行
telnet 127.0.0.1 9003，如果连不上，先关掉其他占端口的进程（比如另一个 PhpStorm 实例、VS Code 的 PHP Debug 插件）
xdebug_info() 输出里 “IDE Key” 和 PhpStorm 底部状态栏显示的一致，再动鼠标。 
