断点不触发的根本原因是xdebug.mode未设为debug；Xdebug 3+已废弃xdebug.remote_enable等旧参数，必须显式配置xdebug.mode=debug（或debug,develop），且需确认PHP加载了正确php.ini、xdebug.client_host指向正确主机、Path Mapping路径严格匹配。
xdebug.mode=debug 没配对，断点就永远不触发——这不是 PhpStorm 的问题，是 PHP 运行时压根没启动调试器。
为什么断点点了没反应？先查 xdebug.mode
Xdebug 3 彻底废弃了 xdebug.remote_enable 等旧参数，只认 xdebug.mode。它必须显式包含 debug，例如：xdebug.mode=debug 或 xdebug.mode=develop,debug。
常见错误现象：
- phpinfo() 页面里搜不到
xdebug.mode这一行 → Xdebug 没加载，或版本低于 3.0 - 断点红点正常显示，但刷新页面毫无反应 →
xdebug.mode缺失或拼错（比如写成debog） - CLI 脚本能断，Web 请求不能 → Apache/Nginx 和 CLI 用的是不同
php.ini，得分别检查
验证方式：在浏览器打开 phpinfo()，Ctrl+F 搜 xdebug.mode；终端执行 php -i | grep xdebug.mode 查 CLI 配置。
xdebug.client_host 别硬写 localhost
Docker、WSL、MAMP/WAMP 下，localhost 在 PHP 容器或子系统里指向自己，不是你的开发机。结果就是 Xdebug 找不到 PhpStorm，连接超时。
- Docker 环境：改用
host.docker.internal（Mac/Windows）或宿主机网关如172.17.0.1（Linux） - WSL2：用 Windows 宿主机的真实 IP（查
ipconfig中的 IPv4 地址），别用localhost - WAMP/MAMP：确认 Apache 使用的
php.ini路径，有些包会把配置分散在多个 ini 文件里
顺手加一句：xdebug.client_port 默认是 9003，不是 9000；改了端口就得同步改 PhpStorm 的 Settings → PHP → Debug → Debug port。
立即学习“PHP免费学习笔记（深入）”；
Path Mapping 错一位，断点就变灰色
PhpStorm 显示 “Cannot find a local copy of the file on server” 或断点变空心灰色，基本是 Path Mapping 配置错了。它不是“本地路径映射到任意远程路径”，而是“PHP 解析时看到的绝对路径” ↔ “你本地项目在硬盘上的绝对路径” 一对一匹配。
- ThinkPHP/Laravel 等框架常把 Web 入口放在
public/目录，而$_SERVER['SCRIPT_FILENAME']返回的是类似/var/www/html/public/index.php—— 这个路径必须和你本地路径（如E:\www\project\public\index.php）严格对应 - Windows 用户特别注意反斜杠：
php.ini和服务器配置里统一用正斜杠/，避免路径拼接出E:/www/E:\www\public\index.php这种诡异错误 - 用
xdebug_info()页面里的$_SERVER['SCRIPT_FILENAME']值作为校验依据，比猜更可靠
浏览器插件失效？手动加参数最稳
Xdebug Helper 插件图标变绿了，但断点还是不进？很可能是域名没进白名单，或插件被浏览器策略禁用了 Cookie/参数注入。
- 最干净的验证方式：
curl "http://localhost/test.php?XDEBUG_SESSION_START=PHPSTORM"，绕过所有前端干扰 - 确保
xdebug.idekey=PHPSTORM（默认值），且 PhpStorm 的Settings → PHP → Debug → DBGp Proxy → IDE key保持一致 - 开发阶段可临时设
xdebug.start_with_request=yes，省去每次加参数，上线前务必关掉
真正卡住人的，往往不是哪一步不会做，而是 xdebug.mode 没生效、client_host 指向了错误网络栈、或者 Path Mapping 差了一个目录层级——这三个点对不上，其他全白搭。
