Xdebug性能分析需按需触发：设xdebug.mode=profile且xdebug.start_with_request=no，通过XDEBUG_TRIGGER头部、Cookie或GET参数激活；输出目录须有写权限；报告用KCacheGrind等工具解析，禁用全局开启以防性能拖累。
Xdebug 的性能分析功能不是“开个开关就能出报告”的黑盒工具，它默认是关闭的，且启用后对请求耗时影响显著——不加控制地全局开启 xdebug.mode=profile，会让每个 PHP 请求都生成 cachegrind 文件，拖慢整个开发环境。
怎么让 profile 只在需要时才启动？
Xdebug 3.3+ 强制要求用触发机制控制 profiler 启动，避免无谓开销。硬编码式开启（如 xdebug.profiler_enable=1）在新版中已被废弃，继续使用会导致配置无效或报错。
- 必须设置
xdebug.mode=profile，但同时要禁用自动启动：xdebug.start_with_request=no - 通过 HTTP 头部触发：
XDEBUG_TRIGGER=1或自定义值（如perf），配合xdebug.trigger_value=perf - 也可用 Cookie 触发：
XDEBUG_TRIGGER=perf，效果等同于头部（浏览器插件常用） - 输出目录需手动创建并确保 PHP 进程有写权限：
xdebug.output_dir=/tmp/xdebug
生成的 cachegrind 文件怎么读？
文件名形如 cachegrind.out.123456789.12345，不含语义信息，直接打开是纯文本，人类不可读。必须用图形化分析器解析。
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- Webgrind 是最轻量选择，纯 PHP 实现，扔进 Web 目录即可用，适合快速查看函数级耗时占比
- KCacheGrind（Linux/macOS）或 WinCacheGrind（Windows）支持调用图展开、火焰图、热点函数排序，更适合深挖嵌套调用瓶颈
- 注意：Webgrind 默认只显示 “total inclusive cost” 占比 > 1% 的函数，若想看更细粒度，需改
config.php中的$settings['defaultFunctionPercentage']
为什么开了 profile 却没生成文件？
常见原因不是配置漏了，而是权限、路径或触发条件没满足——日志才是第一线索。
- 先确认
xdebug.log_level=10和xdebug.log=/tmp/xdebug.log已启用，并重启 PHP-FPM - 访问带触发头的页面后，检查日志里是否有
Profiler: enabled或Writing profiling file字样 - 若日志显示
Could not open profiler file，大概率是/tmp/xdebug目录不存在、无写权限，或 SELinux/AppArmor 拦截 - 用
ls -ld /tmp/xdebug看属主和权限，PHP 进程用户（如www-data或nginx）必须对目录有w权限
profile 和 trace 模式能同时开吗？
可以，但不推荐。两者目标不同、开销叠加，容易掩盖真实瓶颈。
-
xdebug.mode=profile,trace会同时生成cachegrind.out.*和trace.*.xt两类文件 - profile 关注「谁最慢」，适合定位高耗时函数；trace 关注「谁被调用了多少次」，适合发现高频低耗小函数的累积效应
- 实际优化中，应先用 profile 找出 top 3 耗时函数，再对它们单独开启 trace，避免全量 trace 导致磁盘爆满或请求超时
- trace 文件默认不压缩，一个中等请求可能生成几十 MB 日志，
xdebug.trace_options=1可启用压缩，但解析时需对应工具支持
真正卡住性能的往往不是单个函数，而是数据库查询未索引、循环内重复调用 API、或 autoload 加载了大量无用类——cachegrind 报告里的高耗时项，只是表象。盯住 include、require、mysqli_query、curl_exec 这些调用，比优化一个 array_merge 更有效。
