xdebug trace文件过大源于默认全量记录和自动开启，须严格控制output_dir权限与路径，并仅通过trigger按需触发；关闭xdebug.collect_params=0、限制xdebug.max_nesting_level=150可大幅压缩体积。

Trace 文件过大爆盘，根本不是磁盘小，而是 Xdebug 默认“全量记录+自动开启”，一开就写满。关键在两件事：output_dir 必须可控，trace 必须按需触发，缺一不可。

output_dir 要提前建好、权限到位、路径别踩坑

输出目录不是配完就完事——它得真实存在、PHP 进程能写、系统策略不拦截：

• 路径别用 /var/tmp 或 /tmp 下未创建的子目录；推荐显式创建：mkdir -p /tmp/xdebug-trace && chown www-data:www-data /tmp/xdebug-trace（用户按实际 PHP 进程用户调整）
• SELinux 或 AppArmor 启用时，/tmp 可能被限制；可改用 /var/log/php-xdebug/ 并确保上下文正确（semanage fcontext -a -t httpd_log_t "/var/log/php-xdebug(/.*)?"）
• 别依赖相对路径；xdebug.output_dir = "/tmp/xdebug-trace" 必须是绝对路径，且不能拼错字母（常见误写为 xdebug_output_dir）
• 文件名加时间戳和上下文，避免覆盖和混淆：xdebug.trace_output_name="trace.%c.%t"（%c 是脚本名哈希，%t 是微秒时间戳）

绝不能全局开 trace，必须用 trigger 精准控制

Xdebug 3+ 已废弃 xdebug.auto_trace=1，硬开等于自毁。所有 trace 必须手动触发：

Xdebug 3.4.1

Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有

下载

• 启用模式：xdebug.mode=trace（仅此一项不够，必须配合触发）
• 禁用自动启动：xdebug.start_with_request=trigger（不是 yes！设成 yes 就全量写盘）
• 触发方式任选其一：
  — URL 参数：?XDEBUG_TRIGGER=1
  — 请求头：XDEBUG_TRIGGER: 1
  — Cookie：XDEBUG_TRIGGER=1
• Nginx 中若需固定路由触发，可用：fastcgi_param QUERY_STRING "$query_string&XDEBUG_TRIGGER=1";，但仅限调试接口，切勿对全站生效

三招压缩 trace 体积，从 GB 级降到 MB 级

即使按需触发，深层嵌套 + 参数序列化仍会让 trace 文件迅速膨胀。关掉冗余采集最有效：

• 关闭函数参数记录：xdebug.collect_params=0（默认为 1，设为 0 后不再序列化入参，体积直降 40–70%）
• 限制调用栈深度：xdebug.max_nesting_level=150（默认 256，设太高易遇无限递归，150 足够覆盖典型 Web 请求链路）
• 禁用变量值展开：xdebug.var_display_max_depth=3（调试时 IDE 展开变量才用到，不影响 trace 文件大小，但能防止本地卡死）

生成后怎么快速定位问题？别硬打开大文件

一个 200MB 的 trace.abc123.xt 文件，用文本编辑器打不开，也不该打开：

• 用 grep 快速筛关键行为：grep -E "(mysqli|PDO|file_get|curl_exec)" /tmp/xdebug-trace/trace.* | awk '{print $1,$NF}' | sort -k2 -nr | head -10（找耗时长的 IO 调用）
• 用 head -n 1000 查前几屏，看是否反复进入同一函数（疑似递归或循环）
• 真正要分析完整流程时，优先用 VS Code + PHP Debug 插件 加载 trace 文件，它支持按函数过滤、时间轴跳转，比纯文本高效得多