PhpStorm怎么使用断点调试PHP_PhpStorm如何设置断点单步执行查看变量值【详解】-phpstorm-PHP中文网

断点无效的根本原因是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 版本、PHP SAPI 类型（Apache/FPM/CLI）、网络拓扑、路径映射这四者只要一个对不上，就卡在第一步。别急着单步，先确认 xdebug_info() 输出里 “IDE Key” 和 PhpStorm 底部状态栏显示的一致，再动鼠标。