xdebug.mode=profile是唯一启用profiling的开关，需配合xdebug.start_with_request=trigger才能生效；output_dir须有写权限且为绝对路径；生成cachegrind文件需用kcachegrind等工具分析。
xdebug.mode=profile 是唯一启用 Profiling 的开关
Xdebug 3.0 彻底废弃了 xdebug.profiler_enable、xdebug.profiler_enable_trigger 这类独立布尔开关。所有功能都收归 xdebug.mode 统一控制，它接受逗号分隔的字符串，比如 debug,profile。只设 profile 就只开性能分析，不启动调试器。
常见错误是沿用 2.x 写法，单独加 xdebug.profiler_enable=1 —— 这在 3.x 中完全被忽略，不会报错但也不会生成任何 cachegrind 文件。
-
xdebug.profiler_enable→ 已移除，改用xdebug.mode=profile -
xdebug.profiler_enable_trigger→ 已移除，改用xdebug.start_with_request=trigger -
xdebug.profiler_output_dir→ 改为xdebug.output_dir（注意：该路径必须 PHP 进程有写权限，且 Web 服务器用户如 www-data 能访问） -
xdebug.profiler_output_name→ 改为xdebug.output_name，支持占位符如cachegrind.out.%t.%p
xdebug.start_with_request 控制触发时机
这个参数决定了 profiling 在什么条件下启动。它有三个合法值：default（始终开启，不推荐）、trigger（需显式触发）、never（关闭，即使 xdebug.mode=profile 也无效）。
最容易踩的坑是只配了 xdebug.mode=profile 却没设 xdebug.start_with_request —— 默认值是 never，结果 profile 完全不工作。
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- Web 场景必须设为
trigger，否则只有 CLI 脚本能触发 - 配合
xdebug.trigger_value=PROFILING，请求中带XDEBUG_TRIGGER=PROFILING（GET/POST/Header 均可）才生效 - 若用 cURL 测试：
curl -H "XDEBUG_TRIGGER: PROFILING" http://localhost/test.php
输出文件名和路径必须手动确认
xdebug.output_dir 指定的目录不会自动创建，PHP 也不会报错提示“目录不存在”，而是静默失败——文件根本不会生成。这点和 2.x 表现一致，但 3.x 日志更不透明，排查难度更高。
另一个常被忽略的是权限问题：PHP-FPM worker 进程运行用户（如 www-data）必须对 xdebug.output_dir 有写权限，否则 cachegrind.out.* 文件为空或缺失。
- 建议用绝对路径，例如
/var/tmp/xdebug，避免相对路径歧义 - 检查权限：
sudo -u www-data touch /var/tmp/xdebug/test - 文件名模板中
%t是时间戳，%p是进程 ID，%r是随机数，避免冲突
生成的 cachegrind 文件要靠外部工具打开
Xdebug 3.x 不再内置 Web 界面（如旧版的 profiler GUI），只生成标准 cachegrind 格式文件，必须用第三方工具加载分析。
常见组合是：KCacheGrind（Linux/macOS 桌面）、QCacheGrind（Windows）、或 Web 版 WebGrind（需额外部署 PHP 环境）。注意：这些工具不解析 Xdebug 3.3+ 新增的内存快照字段，仅支持函数调用耗时与调用次数。
- 文件名形如
cachegrind.out.1745261100.12345，不是profile或log后缀 - 若用
webgrind，确保其config.php中$storageDir指向正确的xdebug.output_dir - 大项目生成的文件可能超百 MB，KCacheGrind 加载慢，可先用
cg_merge合并多个小文件
xdebug.mode 和 xdebug.start_with_request 必须成对出现，缺一不可；output_dir 权限和路径必须人工验证；触发逻辑从“全局开关”变成“请求级条件”，稍不注意就静默失效。
