“Connection finished”表明Xdebug已启动且PHP脚本执行完毕，但PhpStorm未成功建立调试握手，主因是client_host或client_port不匹配、PhpStorm未开启监听、防火墙拦截或IDE key/路径映射错误。
“Connection finished”不是成功信号，而是 Xdebug 主动断开的明确提示——说明请求确实到达了 PHP，但调试器没连上 PhpStorm，或者连上了却立刻被关掉。
为什么看到“Connection finished”就代表断点失效
这是 Xdebug 日志里典型的失败标识，常见于 Xdebug 已启动、PHP 脚本也执行完了，但 PhpStorm 没收到任何调试握手请求。根本原因不是代码没跑，而是通信链路在建立连接后几毫秒内就中断了。
典型诱因包括：
- Xdebug 尝试连的
client_host（比如127.0.0.1）和 PhpStorm 实际监听的网络接口不匹配（尤其在 Docker/WSL 场景下，localhost可能指向容器外或容器内） -
xdebug.client_port和 PhpStorm 的Debug port不一致（Xdebug 3 默认是9003，但很多人还按旧习惯配成9000） - PhpStorm 没开启监听：忘记点
Start Listening for PHP Debug Connections（小电话图标），或监听状态已自动关闭（比如 IDE 切换项目后重置） - 防火墙 / WSL2 的 NAT 策略拦截了回连流量，Xdebug 能发请求出去，但 PhpStorm 的响应进不来
检查 Xdebug 是否真在运行且配置正确
别只信 php -v 输出里有 Xdebug 字样——它可能加载了，但模式没开。Xdebug 3+ 必须显式启用调试模式：
立即学习“PHP免费学习笔记（深入）”；
- 运行
php --ini确认实际生效的php.ini路径，然后检查其中是否含：xdebug.mode=debug<br>xdebug.start_with_request=yes<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003
- Windows 下若用 WSL，
client_host很可能得填 Windows 主机的 IP（如192.168.1.100），而不是localhost；macOS/Linux 同理，Docker 容器内要填宿主机网关（如host.docker.internal） - 临时加日志确认行为：
xdebug.log=/tmp/xdebug.log<br>xdebug.log_level=7
，然后触发一次请求，看日志末尾是否出现Connection to client successfully established—— 如果只有Connection finished，说明连是连上了，但马上断了
PhpStorm 监听端口和路径映射必须严丝合缝
断点位置对不上，也会导致“连接完成但不中断”。这不是通信问题，而是 PhpStorm 找不到对应源码行：
- 进入
Preferences → PHP → Servers，确认你配置的服务器名称、主机、端口与当前请求 URL 匹配；勾选Use path mappings，并确保本地项目路径（如/Users/you/project）和远程/容器内路径（如/var/www/html）一一映射 - 路径含中文或空格？Xdebug 3.2+ 在这类路径下解析不稳定，
Connection finished高发区，务必改用纯英文路径 - CLI 调试时，Run Configuration 的
Interpreter options里加-d xdebug.mode=debug -d xdebug.start_with_request=yes，避免依赖全局 ini 设置（尤其当你有多个 php.ini 时） - 检查
Preferences → PHP → Debug：Debug port 必须和xdebug.client_port完全一致；勾选Can accept external connections（否则只收 localhost 来的连接）
最容易被忽略的三个硬性条件
这三个点只要漏一个，“Connection finished” 就几乎必然出现，且毫无报错提示：
- PhpStorm 必须处于“正在监听”状态：右下角状态栏有
Listening for PHP Debug Connections提示，或手动点顶部菜单Run → Start Listening for PHP Debug Connections - 浏览器或 CLI 必须携带有效调试触发参数：Web 请求需带
?XDEBUG_SESSION_START=PHPSTORM（Xdebug Helper 插件默认用这个 key）；CLI 需提前设环境变量XDEBUG_CONFIG="idekey=PHPSTORM" - PHP 进程启动时，
xdebug.idekey值必须和 PhpStorm 里 Server 配置中的IDE key完全一致（大小写敏感），默认是PHPSTORM，不是phpstorm或空值
路径映射错一位、idekey 多个空格、监听按钮没点——这些都不会报错，只会安静地显示“Connection finished”。
