PhpStorm 的“Start Listening for PHP Debug Connections”监听 Xdebug 主动发起的 DBGp 协议连接，端口默认9003，仅接收不主动请求；连接建立需满足 xdebug.mode=debug 生效、client_port 与 IDE 端口一致、IDE Key 匹配且路径映射正确。
PhpStorm 的“Start Listening for PHP Debug Connections”到底监听什么
它监听的是 Xdebug 主动发起的 dbgp 协议连接，不是 HTTP 请求，也不是端口扫描。只要 Xdebug 配置正确、PHP 脚本执行时触发了调试会话，且 PhpStorm 正在监听同一端口（默认 9003），连接就会建立。
常见误解是以为“点了电话图标就万事大吉”，其实它只负责接收——Xdebug 是否发、何时发、发给谁，全由 php.ini 配置和请求上下文决定。
-
xdebug.start_with_request=yes：每次请求都强制发起调试连接（适合本地开发，但会拖慢响应） -
xdebug.start_with_request=trigger：仅当存在XDEBUG_SESSION_START参数、XDEBUG_SESSIONCookie 或XDEBUG_PROFILE等触发标记时才连接 - 若用 Docker / WSL / Sail，
xdebug.client_host不能写127.0.0.1，得填宿主机网关（如10.0.2.2或host.docker.internal）
为什么点了监听图标，断点却从不命中
最常被忽略的是路径映射（Path Mapping）缺失，尤其在容器或远程环境里。PhpStorm 收到 Xdebug 连接后，会拿着脚本的绝对路径（比如 /var/www/html/index.php）去本地项目里找同名文件——找不到就直接跳过断点，连提示都不弹。
检查方式：在调试窗口底部看 “Debug” 工具栏右侧是否出现黄色感叹号图标；或者留意 Event Log 里有没有 Cannot resolve path mapping 提示。
立即学习“PHP免费学习笔记（深入）”；
- 进
Settings → PHP → Servers，选中你的服务器配置 - 勾选
Use path mappings - 左侧填项目根目录（如
/Users/you/project），右侧填服务器上对应路径（如/var/www/html） - 不确定远程路径？用
sail shell或docker exec -it xxx bash进容器，执行pwd确认当前工作目录
浏览器端触发调试的三种可靠方式对比
URL 参数最直白，插件最省事，Cookie 最隐蔽——但三者底层都只是让 Xdebug 检测到一个“该启动调试”的信号，没有本质区别。
-
?XDEBUG_SESSION_START=PHPSTORM：手动拼 URL，适合快速测试，但容易漏掉或误传（比如参数被 Nginx 重写规则截断） - Xdebug Helper 插件：点击图标切换 Debug/Profile/Off 状态，自动注入 Cookie，推荐日常使用；注意确认插件右键菜单里选的是
Debug，不是Profile -
Cookie: XDEBUG_SESSION=PHPSTORM：Postman 或 cURL 可直接设置，适合 API 调试；注意 Cookie 名大小写敏感，PHPSTORM必须全大写
如果用了 xdebug.idekey=PHPSTORM，那所有方式都必须匹配这个值，否则 PhpStorm 直接忽略连接请求。
监听状态能持续多久？要不要每次都点一次
监听是常驻的，只要 PhpStorm 没关、没禁用、没报错，它就一直开着。你不需要每次刷新页面都点一次电话图标——点了之后图标变绿，代表已启用；灰色才是关闭状态。
但要注意两个实际干扰项：
- IDE 自动休眠：某些 macOS/Linux 系统在屏幕锁屏或 IDE 失焦超时后，会暂停监听线程；可进
Settings → Appearance & Behavior → System Settings关闭 “Suspend when app is in background” - 防火墙拦截：Windows Defender 或第三方安全软件偶尔会阻止
9003端口入站连接，临时关闭测试下是否恢复 - 多项目共用监听：一个 PhpStorm 实例只能监听一个端口，如果你同时开多个项目，且都配了
9003，后启动的项目会覆盖前者的路径映射，导致断点错乱
真正容易被绕过的，是 xdebug.mode=debug 和 xdebug.client_port=9003 这两个配置项在不同 PHP SAPI（CLI/FPM/CGI）下的生效差异——它们可能只对 CLI 生效，而 Web 请求走的是 FPM，结果 phpinfo() 显示正常，但浏览器就是连不上。
