Xdebug的trace模式用于定位逻辑路径和隐藏调用，profile模式才是查执行效率瓶颈的正解；两者不可混用，必须单独启用并关闭其他模式，否则生成文件无法被工具识别。
直接说结论：Xdebug 的 trace 模式适合定位逻辑路径和隐藏调用，profile 模式才是查执行效率瓶颈的正解；两者不能混用，且必须关掉再开，否则生成的文件无法被工具识别。
怎么开启函数调用跟踪（trace）并避免日志爆炸
trace 会记录每一行代码执行、每次函数进入/退出、参数和返回值——IO 和磁盘写入压力极大，稍不注意就填满磁盘。
-
xdebug.mode=trace是 Xdebug 3+ 的启用方式，旧版的xdebug.auto_trace=1已失效 - 务必配合
xdebug.start_with_request=trigger，否则每个请求都写 trace 文件 - 用
XDEBUG_TRIGGER=1请求头或 URL 参数（如?XDEBUG_TRIGGER=1）手动触发，避免污染正常流量 - 输出目录必须提前创建并确保 PHP 进程有写权限：
xdebug.output_dir="/tmp/xdebug-trace"（别用/var/tmp，某些系统下 SELinux 会拦截） - 默认文件名是
trace.XXXXXXX.xt，可通过xdebug.trace_output_name="trace.%c.%t"改成带上下文和时间戳的格式，方便归档
怎么生成有效的性能分析文件（cachegrind）
profile 模式输出的是 cachegrind 兼容格式，供 qcachegrind 或 webgrind 可视化分析。但很多人生成的文件打不开，问题几乎全出在配置时机上。
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 必须设为
xdebug.mode=profile，不是develop,profile混合——Xdebug 3 会忽略 profile 功能，除非它是 mode 中唯一或显式启用的项 -
xdebug.profiler_enable_trigger=1是安全做法；xdebug.profiler_enable=1会全局开启，上线后极易拖垮服务 - 确认
xdebug.profiler_output_dir目录存在、可写，且路径末尾不要加斜杠（/tmp/xdebug✅，/tmp/xdebug/❌ 在部分版本中会导致写入失败） - 生成的文件名形如
cachegrind.out.12345，注意不是.xt或.log后缀——如果看到别的后缀，说明根本没进 profile 模式 - CLI 脚本调试时，需显式传参：
XDEBUG_CONFIG="profiler_enable=1" php script.php，环境变量方式比 ini 配置更可靠
为什么 qcachegrind 打不开文件，或者 Call Graph 显示空白
这不是 Xdebug 问题，而是 graphviz 的 dot 命令不可达或路径错位。webgrind 同理。
- 先验证
dot -V是否能输出版本号；macOS 用brew install graphviz后，dot默认在/usr/local/bin/dot - qcachegrind 不依赖配置，只要文件格式对就能打开；但 webgrind 必须指定
$dotExecutable，且不能写成/usr/bin/dot（macOS 上不存在） - Linux 下常见错误是权限：webgrind 进程用户（如 www-data）无权执行
dot，建议改用sudo setcap cap_sys_chroot+ep /usr/bin/dot或切换为 root 启动 webgrind - Call Graph 空白还有一种可能：Xdebug 没收集到调用关系，检查是否误开了
xdebug.collect_functions=0（应为 1）或xdebug.skip_frames=1过高导致顶层调用被跳过
开发机与容器间调试失败的典型断点
本地 IDE 连不上容器里的 PHP，90% 是网络层或地址配置错了，而不是 Xdebug 版本问题。
-
xdebug.client_host必须填宿主机真实 IP（如192.168.1.105），填host.docker.internal仅限 Docker Desktop for Mac/Windows；Linux 需用ip route | awk '{print $3}'查网关 -
xdebug.client_port默认是 9003（Xdebug 3+），不是旧版的 9000；PHPStorm 默认监听 9003，但很多教程没更新这点 - Nginx + PHP-FPM 场景下，重启的是
php-fpm进程，不是 Nginx；改完配置后漏 reload php-fpm，Xdebug 根本没加载 - Docker 中若用
--network host，xdebug.client_host应设为127.0.0.1；但多数情况不该用 host 网络，而应通过端口映射 + 正确 client_host 配合 - 验证是否生效：访问
phpinfo()页面搜xdebug.mode，看到当前 mode 是debug或profile，才算真正启用
最常被忽略的一点：Xdebug 3 的 mode 是互斥开关，不是叠加标签。想同时看堆栈又做性能分析？不行。要么切到 profile 模式跑一次，要么切回 debug 模式单步跟——没有“两全其美”的配置，只能分阶段操作。
