Xdebug断点不生效的四大原因：未启用Xdebug模块、未正确配置路径映射、未匹配调试端口与网络环境、未忽略外部库导致误入vendor。需逐项验证php -v、phpinfo()、xdebug_info()、lsof及PhpStorm路径映射设置。
断点设了但根本不暂停？先确认Xdebug是否真在跑
最常见的假象是：行号左边点了红点，以为断点生效，结果刷新页面毫无反应。这几乎总是因为PHP进程压根没走Xdebug通道。
执行 php -v，输出里必须带 with Xdebug 字样；再跑 php --ini 找到加载的 php.ini，确认里面启用了 xdebug.mode=debug（PHP 8.1+）或旧版的 xdebug.remote_enable=1。别只改CLI配置——Web服务器（Apache/Nginx + PHP-FPM）用的是另一套配置文件，/etc/php/8.2/fpm/php.ini 和 /etc/php/8.2/cli/php.ini 得分别检查。
- 用
phpinfo()页面确认 Xdebug 模块已加载，且xdebug.mode显示为debug - 浏览器访问时，确保请求由Web服务器处理（不是直接双击打开HTML），否则Xdebug不触发
- CLI调试要加
php -dxdebug.mode=debug script.php，不能只靠IDE里Run → Debug
Step Into（F7）跳进vendor或Xdebug源码？关掉外部库追踪
按F7想进自己写的 calculateTotal()，结果卡在 vendor/composer/ClassLoader.php 第42行，这不是你该关心的逻辑。这是默认行为：Step Into会无差别钻进所有函数调用栈。
真正需要的是「只进自己代码」。进入 Settings > PHP > Debug > Stepping，勾选 Ignore external libraries。这个开关会自动过滤掉 vendor/、phpstorm-stubs 和PHP内置扩展里的函数。
立即学习“PHP免费学习笔记（深入）”；
- 临时想跳过某一行调用？右键该行 →
Force Step Over，整条语句当黑盒处理 - 想精准进某个函数？把光标停在函数名上（比如
processOrder()），再按F7，比盲目按更稳 - Step Over（F8）才是日常主力，它只执行当前行，不进任何函数体，适合快速扫过无关逻辑
路径映射错一个字符，变量全变null
断点能停，但变量窗里全是 null 或 undefined，或者“Variables”面板空空如也？八成是本地路径和服务器路径没对齐。
比如你的项目在 /home/user/project，但PHP实际运行在 /var/www/html，PhpStorm的 Servers 配置里就必须填上严格对应的映射：/home/user/project ↔ /var/www/html。少个斜杠、多级目录没对齐、大小写不一致（Linux敏感），都会导致Xdebug传回来的变量无法绑定到源码位置。
- 检查路径映射时，打开
Settings > PHP > Servers，勾选Use path mappings，再逐字核对左右两栏 - 用
xdebug_info()函数输出调试信息，在浏览器里看$_SERVER['SCRIPT_FILENAME']真实路径，和映射左栏比对 - Windows用户注意反斜杠
\要换成正斜杠/，PhpStorm不认C:\project这种写法
调试监听开着，但连接总超时？查端口和网络策略
右下角显示 Debug listening…，浏览器也访问了URL，断点就是不触发——问题常出在端口通不通。
Xdebug默认连 127.0.0.1:9003，但PhpStorm监听端口必须和 xdebug.client_port 完全一致。更隐蔽的问题是：某些Linux发行版（如Ubuntu 24.04）默认启用 ufw 防火墙，会拦掉9003端口；Docker容器里跑PHP时，xdebug.client_host 不能写 127.0.0.1，得换成宿主机网关IP（比如 host.docker.internal）。
- 终端执行
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows），确认9003端口确有PhpStorm进程监听 - 如果用Docker，
xdebug.client_host改成host.docker.internal（Docker Desktop）或容器网关IP（Docker CE） - 公司内网有时会禁用回环地址调试，可临时试
xdebug.client_host=10.0.2.2（VirtualBox）或改用xdebug.discover_client_host=1
xdebug_info() 输出、lsof 端口状态、路径映射三处，比反复重启服务有效得多。 
