详解xdebug3中的xdebug.mode配置组合教程-php教程-PHP中文网

xdebug.mode是功能模式总闸，仅设debug不触发断点，需配合start_with_request=yes或外部触发；常见组合如debug,develop用于日常调试，profile用于性能分析，coverage用于ci覆盖率，develop适用于仅增强错误显示场景。

详解xdebug3中的xdebug.mode配置组合教程

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

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 的部分行为（例如不监听客户端连接）