Xdebug 2.x 升级 3.x 配置变化详解

Xdebug 3.x 对性能分析（profile）的启用机制进行了彻底重构：不再依赖已废弃的 `xdebug.profiler_enable`，而是必须通过 `xdebug.mode=profile` 显式激活，并配合 `xdebug.start_with_request` 精准控制触发时机（如 always、trigger 或 manual），同时所有输出路径统一由 `xdebug.output_dir` 管理——若配置不当，不仅 cachegrind 文件无法生成，连 `var_dump()` 高亮都会失效；更隐蔽的是，旧版 Webgrind 因仍硬编码读取已被移除的 `xdebug.profiler_output_dir`，会导致“文件明明存在却显示找不到”的静默失败。升级不是简单改参数，而是理解并适配这套全新的模式驱动架构，否则调试和性能分析将全面失灵。

profile功能必须用xdebug.mode=profile开启

Xdebug 3.x 彻底移除了 xdebug.profiler_enable 这类独立开关，profile 不再是“开/关”二选一，而是被纳入统一的模式系统。不设 xdebug.mode=profile，哪怕其他参数全对，cachegrind.out.* 文件也永远不会生成。

常见错误现象：/tmp 目录下始终没有 cachegrind.out.* 文件，var_dump() 也不高亮——因为 xdebug.mode 没包含 profile 或 debug，Xdebug 实际处于“休眠”状态。

• xdebug.mode 可同时启用多个模式，用英文逗号分隔，例如：profile,debug 或 profile,trace,develop
• 仅需设一次 xdebug.mode，无需再配 xdebug.profiler_enable=1（该配置已废弃，设了也无效）
• 如果只想要 profile，不要调试，就别加 debug——避免不必要的性能损耗和端口监听

xdebug.start_with_request决定profile何时触发

原来靠 xdebug.profiler_enable_trigger + URL 参数或 cookie 控制是否启动 profile；现在统一由 xdebug.start_with_request 管理触发时机，取值只有三个：yes、no、trigger。

使用场景：

• yes：每个请求都生成 profile 文件（适合本地压测，但生产环境慎用）
• trigger：仅当请求中含特定标识才启动，比如 URL 带 XDEBUG_PROFILE=1 或 cookie 含 XDEBUG_PROFILE=1
• no：完全不自动触发，必须手动调用 xdebug_start_profiling() 函数

注意：xdebug.trigger_value 配合 trigger 使用，例如设为 StartProfileForMe，则需传 XDEBUG_PROFILE=StartProfileForMe 才生效。

输出路径和文件名全由xdebug.output_dir和xdebug.profiler_output_name控制

旧版要分别设 xdebug.profiler_output_dir 和 xdebug.trace_output_dir；Xdebug 3.x 合并为通用的 xdebug.output_dir，所有 profile、trace、gcstats 输出都走这里。

关键点：

• xdebug.output_dir 必须是 PHP 进程有写权限的绝对路径，例如 /tmp 或 /var/tmp/xdebug；相对路径会被忽略
• xdebug.profiler_output_name 默认是 cachegrind.out.%p，其中 %p 是进程 PID；也可用 %s（脚本名）、%r（随机数）等，但 %t（时间戳）在 CLI 下不可靠，建议慎用
• Web 环境下若启用了 opcache，且脚本被缓存，%s 可能固定为 index.php，导致多个请求覆盖同一文件

Webgrind 读不到 profile 文件？检查xdebug.output_dir硬编码位置

很多老版本 Webgrind（如 v1.8 及更早）仍按 Xdebug 2 的逻辑去扫描 xdebug.profiler_output_dir，而这个配置项在 3.x 中已不存在。结果就是界面显示“no profile files found”，实际文件明明在 /tmp 里。

解决办法很直接：

• 打开 Webgrind 的 config.php
• 找到类似 return getcwd() . '/cache'; 的路径返回逻辑
• 强行改成你真实配置的 xdebug.output_dir，例如：return '/tmp';

这个坑不会报错，只会静默失败——文件生成了，工具却视而不见，最容易被忽略。

以上就是《Xdebug 2.x 升级 3.x 配置变化详解》的详细内容，更多关于Xdebug的资料请关注golang学习网公众号！