xdebug.mode=debug是xdebug 3调试前提，但连不上ide主因是client_host不可达、client_port不匹配（应为9003）或start_with_request未触发；断点灰色、“waiting for connection”即典型表现。
xdebug.mode 是 Xdebug 3 的核心开关，不是可选配置项——不设它，绝大多数功能（包括断点调试、覆盖率、性能分析）压根不会加载。
xdebug.mode=debug 为什么连不上 IDE？
只写 xdebug.mode=debug 只是启用了调试协议，但不等于“自动连接”。必须同时满足：
-
xdebug.client_host指向 IDE 所在机器的真实 IP（本地开发用127.0.0.1；Docker 容器内要用宿主机 IP，如172.17.0.1或host.docker.internal） -
xdebug.client_port和 IDE 监听端口一致（Xdebug 3 默认是9003，不是旧版的9000） -
xdebug.start_with_request设为yes或用触发机制（如 GET 参数XDEBUG_SESSION_START=1），否则 HTTP 请求不会发起连接
常见错误现象：断点灰色不可用、IDE 显示 “waiting for connection” 却无响应——八成是 client_host 不可达或端口被防火墙/其他服务占用。
xdebug.mode=coverage 生成报告为空？
仅配置 xdebug.mode=coverage 不够。PHP CLI 运行 PHPUnit 时，还必须：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 确认 CLI 使用的 php.ini 启用了 Xdebug：
php -m | grep xdebug有输出，且php -i | grep "xdebug.mode"返回包含coverage - PHPUnit 命令显式启用覆盖率收集：
phpunit --coverage-html ./coverage，不能只靠phpunit默认运行 -
phpunit.xml中<include></include>必须精准指向源码目录（如src/），且<exclude></exclude>显式排除测试类和引导文件，否则统计路径错乱 - 避免全局开启
xdebug.start_with_request=yes：CLI 场景下它会让所有脚本变慢，覆盖率应按需启用
典型陷阱：Web 环境配置了 coverage，但跑 phpunit 用的是 CLI 配置，两者 php.ini 完全独立。
多个 mode 能否共存？比如 debug,coverage
可以，xdebug.mode 支持逗号分隔，例如 xdebug.mode=debug,coverage。但要注意：
- 不同 mode 对应不同使用场景：debug 用于交互式断点，coverage 用于测试后静态分析，二者同时启用会增加开销，仅建议临时调试 + 覆盖率验证
- profile 和 trace 模式会生成大量磁盘文件，不要长期与 debug 共存，尤其在线上或 CI 环境
- mode 是位掩码控制，未列出的 mode 功能完全不加载——所以
xdebug.mode=debug下，xdebug.coverage_enable这类旧版参数已无效
真正容易被忽略的是：Xdebug 3 不再区分 “远程调试” 和 “本地调试”，client_host 始终必需，哪怕你只在本机跑 Apache + VS Code，也得填对 127.0.0.1，而不是留空或写 localhost（某些 DNS 解析慢会导致超时）。
