xdebug.mode是功能模式总闸，仅设debug不触发断点，需配合start_with_request=yes或外部触发；常见组合如debug,develop用于日常调试，profile用于性能分析，coverage用于CI覆盖率，develop适用于仅增强错误显示场景。
xdebug.mode 不是开关，而是功能模式的“总闸”，填错值或组合错误，Xdebug 就不会按你预期工作——比如设了 xdebug.mode=debug 却没配 xdebug.start_with_request，断点根本不会触发。
为什么 xdebug.mode 不能只写 debug
Xdebug 3 把所有功能归到 xdebug.mode 下统一控制，它接受逗号分隔的多个模式组合，每个模式激活对应能力：
-
debug：启用远程调试（断点、单步、变量查看） -
develop：增强错误报告（带堆栈、变量上下文），不影响性能分析 -
profile：开启性能分析（生成 cachegrind 文件） -
trace：记录函数调用轨迹（生成 trace 文件） -
coverage：用于代码覆盖率（PHPUnit 集成时需要）
常见误区是只写 xdebug.mode=debug 就以为万事大吉。但 debug 模式本身不自动发起连接——它依赖 xdebug.start_with_request 或外部触发（如 IDE 监听 + 浏览器插件）。没有这个配合，debug 就是“待机状态”。
xdebug.mode 常见组合与适用场景
不同开发阶段需要不同能力组合，硬套一个配置反而低效：
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 日常 Web 调试：
xdebug.mode=debug,develop+xdebug.start_with_request=yes（断点随时生效，错误信息更友好） - 排查性能瓶颈：
xdebug.mode=profile+xdebug.output_dir="/tmp/xdebug（注意：profile 和 debug 不能同时长期开启，会显著拖慢响应） - CI 环境跑覆盖率：
xdebug.mode=coverage+XDEBUG_MODE=coverage环境变量 （避免污染开发配置，CLI 下用环境变量更安全） - 仅增强错误显示（不调试）：
xdebug.mode=develop（适合生产预发布环境，无连接开销）
特别注意：debug 和 profile 同时启用时，Xdebug 会优先处理调试请求；若 profile 已在运行，新调试请求会被拒绝——这不是 bug，是设计上的互斥保护。
容易被忽略的兼容性陷阱
旧版配置里常见的 xdebug.remote_enable=1 或 xdebug.collect_params=4 在 Xdebug 3 中已完全失效。如果 php.ini 里还留着这些，Xdebug 会静默忽略，但可能掩盖真实问题：
-
xdebug.remote_enable→ 必须删掉，由xdebug.mode=debug替代 -
xdebug.collect_params→ 已移除，变量自动采集，无需手动开 -
xdebug.show_local_vars→ 已废弃，develop模式下自动显示局部变量 - 混合写法如
xdebug.mode=debug,develop,profile是合法的，但profile会强制关闭debug的部分行为（例如不监听客户端连接）
验证是否生效，别只看 php -m | grep xdebug，要运行 php --ri xdebug，重点检查输出里的 Mode 行是否匹配你写的值，以及 Status 是否为 enabled。
最常卡住的地方不是路径或端口，而是 xdebug.mode 写对了但没配对 xdebug.start_with_request 或环境变量没传过去——尤其 Docker 或 CLI 场景下，XDEBUG_MODE 环境变量比 php.ini 更优先，且不继承父进程，必须显式注入。
