PhpStorm显示“Waiting for connection”但断点不触发，主因是Xdebug连接被阻塞或连错地址：xdebug.client_host配置错误（如Linux下host.docker.internal不可解析，需改用宿主机IP如172.17.0.1）、xdebug.client_port与PhpStorm Debug port不一致（默认9003易被占用，可改为9009并同步更新php.ini）、残留xdebug.remote_*旧参数导致调试模式静默失效，且须确保路径映射精准、监听已开启。
PhpStorm 显示“Waiting for connection”但断点不触发
这几乎从来不是 PhpStorm 本身的问题，而是 Xdebug 尝试连接时被阻塞或连错地方了。最常见原因是 xdebug.client_host 指向错误，或 xdebug.client_port 与 PhpStorm 的 Debug port 不一致，导致连接静默失败——没有报错，但 IDE 根本收不到请求。
检查步骤：
- 在浏览器打开
phpinfo()页面，搜索Loaded Configuration File，确认你改的是 Web 服务实际加载的php.ini（不是 CLI 的） - 确认
xdebug.mode=debug已启用，且xdebug.start_with_request=trigger（避免无请求时也尝试连接） - 删掉所有
xdebug.remote_*开头的旧配置项（Xdebug 3.x 完全废弃它们，残留会导致整个调试模式失效） - 执行
ping -c 1 host.docker.internal（Docker 场景），不通就换宿主机 IP；Linux 原生 Docker 必须手动设xdebug.client_host=172.17.0.1类似值
Xdebug 9003 端口被占用或提示 “port is busy”
9003 是 Xdebug 3 默认端口，但 PHP-FPM、另一个 PHP 项目、甚至 VS Code 的 PHP debug 插件都可能抢先占住它。PhpStorm 不会自动换端口，只会报错或卡在监听状态。
解决方法：
立即学习“PHP免费学习笔记（深入）”；
- 查端口占用：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows），杀掉对应 PID - 改 PhpStorm 端口：Settings → PHP → Debug → Xdebug → Debug port，比如改成
9009 - 同步改
php.ini中的xdebug.client_port=9009（注意：不要加引号，写成"9009"会被忽略） - 重启 PHP-FPM 或整个容器（
docker restart <container></container>），仅 reload 配置不够
Docker 环境下 Xdebug 连不上 host.docker.internal
host.docker.internal 在 macOS/Windows Docker Desktop 中自动可用，但在 Linux 原生 Docker 或 WSL2 中默认不存在。直接写这个域名，xdebug.client_host 解析失败，连接立刻超时，日志里只显示 Connection to 'host.docker.internal:9003' failed。
补救方案：
- 进容器运行：
ip route | awk '{print $3}' | head -n1，拿到宿主机网关 IP（通常是172.17.0.1） - 把
php.ini中的xdebug.client_host改成这个 IP - 如果用
docker-compose.yml，加这一段显式注入 DNS：
extra_hosts: - "host.docker.internal:host-gateway"
注意：该配置只对 compose 启动的服务生效，docker run 手动启动需加 --add-host 参数。
多个 PHP 项目共存时调试互相干扰
多个项目共用同一个 xdebug.client_port 和 idekey，PhpStorm 只能响应第一个连上来的请求，其余全部丢弃。现象是：A 项目能断点，B 项目完全没反应，控制台也无日志。
隔离方式：
- 为每个项目分配独立端口：A 用
9009，B 用9010，并在各自php.ini和 PhpStorm Debug port 中严格对应 - 启用
Filter debug connection by IDE key（Run → Edit Configurations → PHP Web Page → 勾选此项） - 各项目设不同
xdebug.idekey，如LARAVEL_DEV、WP_LOCAL，并确保浏览器插件或 URL 参数（?XDEBUG_SESSION_START=LARAVEL_DEV）匹配
真正麻烦的不是改配置，而是每次切项目都要核对三处：PhpStorm Debug port、php.ini 的 xdebug.client_port、以及 xdebug.idekey 是否和当前调试会话一致——漏一个，就白等。
