debug toolbar需满足yii_debug=true、yii_env='dev'、allowedips包含当前ip且页面输出完整html；xhprof需php扩展启用、绝对路径引入库、类名前加反斜杠；前者用于宏观性能初筛，后者用于函数级深度分析。
Debug Toolbar 怎么开、怎么看、为什么有时不显示
Yii2 的 debug 模块不是装上就自动弹窗的，它依赖三个硬性条件：开发环境、IP 白名单、以及页面能正常输出 HTML（比如不能是纯 JSON 接口或 AJAX 返回）。最常见问题是配置写了但工具栏不出现——八成是 allowedIPs 没放开，或者入口脚本里 YII_DEBUG 实际为 false。
- 确认
YII_DEBUG === true且YII_ENV === 'dev'（检查入口文件web/index.php开头） - 在
config/web.php的modules中启用模块，并显式放开本地 IP：'allowedIPs' => ['127.0.0.1', '::1'] - 页面必须有完整的
结构；$this->renderAjax()或 API 接口默认不加载 toolbar - 点击 toolbar 底部的 “Database” 标签，可直接看到每条 SQL 的执行时间、是否命中索引；点开慢查询还能跳转到对应代码行（需开启
yii\db\Connection::enableProfiling = true）
XHProf 启动失败的典型原因和最小可行路径
xhprof_enable() 调用后没生成数据、xhprof_runs_save() 报类未找到、或者报告页面空白——这些基本都卡在路径和命名空间上。XHProf 不是 Yii 原生组件，它依赖外部 PHP 扩展 + 手动引入的两个核心库文件，漏一个就断链。
- 必须确保 PHP 已加载
xhprof扩展：php -m | grep xhprof；Ubuntu 下常用sudo pecl install xhprof（注意 PHP 版本兼容性） -
include_once的路径必须是绝对路径或相对于当前文件的正确相对路径；推荐用__DIR__ . '/vendor/xhprof/xhprof_lib/utils/xhprof_lib.php'避免歧义 - 保存运行结果时，
\XHProfRunsDefault前面的反斜杠\不能省——否则 PHP 会在当前命名空间里找这个类，报Class 'app\controllers\XHProfRunsDefault' not found - 示例写法：
$objXhprofRun = new \XHProfRunsDefault(); $objXhprofRun->save_run(xhprof_disable(), 'user-login-' . time());
什么时候该用 Debug Toolbar，什么时候必须切 XHProf
Debug Toolbar 是“宏观体检”，适合快速发现数据库 N+1、视图渲染耗时高、内存突增等表层问题；XHProf 是“显微解剖”，能定位到某一行 foreach 循环里调用的某个辅助函数占了 60% 时间。别用错场景。
- 上线前压测发现平均响应 1.2s → 先开 Debug Toolbar 看 Database 和 Timeline 标签，确认是不是 SQL 或日志写入拖慢
- 某个接口从 200ms 慢到 800ms，但 Debug Toolbar 显示 SQL 只占 50ms → 这时就要上 XHProf，在控制器
action开头加xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY)，跑一次请求看火焰图 - Debug Toolbar 在生产环境禁用（性能损耗约 15–20%），XHProf 也绝不能长期开着——它会让每个函数调用都记录栈帧，QPS 下降明显
EXPLAIN + Debug Toolbar 联合查慢查询的实操姿势
Debug Toolbar 里点了慢 SQL，只告诉你“这条语句花了 320ms”，但不知道为什么慢；这时候得立刻补上 EXPLAIN 分析。Yii2 查询构建器本身不支持直接 EXPLAIN，得绕一下。
- 在控制器里临时构造命令：
$sql = Post::find()->where(['status' => 1])->createCommand()->getRawSql(); $explainSql = 'EXPLAIN ' . $sql; $explainResult = Yii::$app->db->createCommand($explainSql)->queryAll(); print_r($explainResult); - 重点关注
type字段：如果出现ALL，说明全表扫描；key为空表示没走索引；rows数远大于实际返回行数，说明索引选择率差 - 别只看单条 SQL —— Debug Toolbar 的 “Database” 标签页右上角有个“Show all queries”，点开看是不是同一请求发了 12 次相似查询（典型 N+1）
