Xdebug 3 断点不命中需确认其是否运行：检查配置仅保留xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host=127.0.0.1，确保URL含?XDEBUG_SESSION_START=PHPSTORM，PhpStorm监听9003端口且路径映射准确。
断点不命中？先确认 Xdebug 3 是否真在运行
PHPStorm 断点灰色、没反应，八成不是代码写错了，而是 Xdebug 根本没连上 IDE。Xdebug 3.x 彻底废弃了 xdebug.remote_* 系列配置（比如 xdebug.remote_host），继续留着会直接报 Unknown configuration setting 错误，且 PHP 启动失败。
只保留这三行才有效：
-
xdebug.mode=debug：必须是debug，不是develop或profile -
xdebug.start_with_request=trigger：设为trigger更安全；设yes会导致 CLI 脚本、健康检查接口也被强制调试 -
xdebug.client_host=127.0.0.1：别写localhost，某些系统 DNS 解析失败；Docker 容器内访问宿主机请用host.docker.internal
顺手加上：xdebug.client_port=9003（Xdebug 3 默认端口）、xdebug.log=/tmp/xdebug.log（出问题第一眼就查它）。
浏览器请求没触发调试？缺了这个参数
?XDEBUG_SESSION_START=PHPSTORM 不是可选动作，是硬性开关。Xdebug 3 默认不自动连，不带这个参数，xdebug.start_with_request=trigger 就不会生效。
立即学习“PHP免费学习笔记（深入）”；
最快验证方式：
- 手动在 URL 末尾加
?XDEBUG_SESSION_START=PHPSTORM（注意大小写，PhpStorm 默认 key 是PHPSTORM） - 装 JetBrains 官方插件 IDE Helper（Chrome/Firefox），点虫子图标一键激活，自动管理 cookie
- 如果用了 Nginx/Apache 反向代理，确认
proxy_pass没丢掉$args，否则 query string 被过滤，参数根本传不到 PHP
PhpStorm 没监听？绿色电话图标 ≠ 真在监听
工具栏那个小电话图标变绿，只代表“监听开关已打开”，不代表端口真在 LISTEN 状态。
必须做两件事：
- 进入
Settings > PHP > Debug > Xdebug，确认Debug port是9003（不是旧版9000） - 终端执行：
sudo lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows），看到LISTEN才算成功 - Windows Defender、火绒等杀软常静默拦截
9003端口；临时关闭测试一次，能连上就是它拦的
路径映射错一个字符，断点照样不进
即使 Xdebug 连上了、浏览器带了参数、PhpStorm 在监听，路径映射（Path Mapping）错一个斜杠或大小写，断点也会跳过。
常见坑点：
- 服务器上文件路径是
/var/www/html/index.php，本地项目根目录却是/Users/me/project，必须在Settings > PHP > Servers里把/var/www/html映射到本地路径 - Windows 下用反斜杠
\配置路径映射，PhpStorm 会识别失败；统一用正斜杠/ - 虚拟主机或 Docker 中的文档根目录（DocumentRoot）和实际 PHP 文件路径不一致时，以
$_SERVER['SCRIPT_FILENAME']输出的真实路径为准
最省事的办法：在 PHP 脚本开头加一行 die(__FILE__);，看浏览器输出的完整路径，再照着配映射。
