必须设xdebug.mode=profile才能启用性能剖析，仅装扩展无效；需配合xdebug.start_with_request=yes或xdebug.trigger_value=perf触发，并确保xdebug.output_dir路径存在、可写且正确挂载。
docker内启用xdebug.profile模式必须设xdebug.mode=profile
只装xdebug扩展但没设xdebug.mode=profile，xdebug.output_dir再怎么配也不会生成分析文件。Xdebug 3 强制要求用xdebug.mode统一开关功能，profile是独立模式，和debug互不干扰。
常见错误是沿用旧版写法，在配置里加xdebug.profiler_enable=1或xdebug.enable_profiler=1——这些在 Xdebug 3 中已废弃，会被忽略。
-
xdebug.mode=develop,profile：同时启用开发增强提示 + 性能剖析（适合本地调试） -
xdebug.mode=profile：仅启用剖析，无调试开销（更贴近真实负载） - 避免写成
xdebug.mode=debug,profile：debug 模式本身就会显著拖慢响应，叠加 profile 更卡
触发 profiling 必须配xdebug.start_with_request或xdebug.trigger_value
默认情况下，xdebug.mode=profile不会自动为每个请求生成文件——它需要显式触发，否则容器启动后根本看不到任何 cachegrind.out.* 文件。
两种触发方式选其一即可：
-
xdebug.start_with_request=yes：每个 HTTP 请求都生成一个 profile 文件（仅限开发环境，日志爆炸快） -
xdebug.trigger_value=perf+ URL 参数：?XDEBUG_TRIGGER=perf（推荐），只对带该参数的请求生效 -
xdebug.start_with_request=trigger：等效于上一条，语义更清晰（Xdebug 3.3+ 支持）
注意：xdebug.trigger_value值区分大小写，且不能含空格或特殊字符；URL 中必须严格匹配，比如?XDEBUG_TRIGGER=perf，写成?XDEBUG_TRIGGER=PERF就无效。
output_dir路径必须映射到宿主机且容器有写权限
xdebug.output_dir=/tmp/xdebug看着没问题，但在 Docker 里常出错：要么目录不存在，要么 PHP 进程没权限写入，要么路径没挂载出来，导致文件“生成了却找不到”。
实操建议：
- 在
Dockerfile中显式创建目录并赋权：RUN mkdir -p /tmp/xdebug && chown www-data:www-data /tmp/xdebug - 确保
docker-compose.yml里挂载了该路径：volumes: - ./xdebug-profiles:/tmp/xdebug - 别用
/var/log或/usr/local/etc这类只读或权限受限路径，PHP-FPM 默认以www-data用户运行，非 root 路径最稳妥
验证是否生效：进容器执行ls -l /tmp/xdebug，确认属主是www-data且有w权限；再访问一次带XDEBUG_TRIGGER的 URL，立刻检查宿主机./xdebug-profiles/下是否出现cachegrind.out.*文件。
分析cachegrind文件前先确认时间戳和内容有效性
生成的cachegrind.out.*文件可能为空、损坏或时间戳异常——尤其当容器反复重启、output_dir挂载错位、或 PHP 进程被 kill 导致写入中断时。
快速验证方法：
- 用
head -n 5 ./xdebug-profiles/cachegrind.out.*看开头是否有version:和cmd:行，没有就是空文件 - 对比文件修改时间与请求时间是否接近，偏差超 10 秒大概率是写入延迟或挂载不同步
- 用
qcachegrind（macOS）或kcachegrind（Linux）打开，若报“invalid file format”或直接空白，八成是文件截断
真正容易被忽略的是：Xdebug profiling 在 CLI 模式下默认不生效（除非手动设xdebug.mode=profile并触发），所以php artisan test这类命令不会自动生成 profile 文件，得加XDEBUG_TRIGGER=perf环境变量才能捕获。
