必须用 yii debug 工具栏的 db 面板精准定位慢查询：先验证工具栏已启用（network 查 /debug/default/toolbar 返回200），再通过排序、profile 标记或 sql 注释快速识别慢sql，最后用 explain 分析执行计划并补索引。
当你在 Yii 项目中发现列表页加载缓慢、接口响应超时，却不确定是哪条 SQL 拖慢了整个请求时，不能靠猜——必须用 Yii Debug 工具栏的 DB 面板精准定位慢查询。它不依赖外部 APM，只要配置正确，每条语句的执行时间、参数、调用栈都一目了然。
确认 Debug 工具栏已真实启用
第一步不是点开面板，而是验证工具栏是否真被加载：访问任意页面后，在浏览器开发者工具 Network 标签页里搜索 debug，看到 /debug/default/toolbar?tag=xxx 成功返回 200 响应，且响应体含 JSON 数据，说明工具栏已渲染；若无此请求或返回 404，说明模块根本没注册成功。
检查入口文件 web/index.php 是否同时满足三件事：【YII_DEBUG 必须为 true】、【$_SERVER['REMOTE_ADDR'] 必须在 allowedIPs 白名单内】、【YII_ENV 必须等于 'dev'】；缺一不可，少一个工具栏就完全不会出现。
直接访问 /debug/default/index，能打开完整调试界面说明模块注册成功；打不开则问题出在模块配置或环境变量上，不是面板设置问题。
让慢查询在 DB 面板里“亮出来”
方法一：开启 SQL 执行时间排序
进入 DB 面板 → 点击「Duration」列标题两次，按降序排列；耗时最长的 SQL 会自动顶到最上面，一眼锁定瓶颈语句。
方法二：手动标记可疑查询块
在控制器或模型中，在疑似慢的查询前后插入 Yii::beginProfile('slow-query-block') 和 Yii::endProfile('slow-query-block')；刷新页面后，Profiling 面板里会出现该命名区块，点击展开就能看到它包裹的全部 SQL 及各自耗时——这比扫全量日志快得多。
方法三：用 SQL 注释主动标注
在查询构建器中加入可识别注释，例如：User::find()->where(['status' => 1])->andWhere(['>=', 'updated_at', $date])->addComment('LIST_PAGE_USER_FETCH')->all();；DB 面板里每条 SQL 的「SQL」列会显示该注释，方便你快速过滤和归类。
查到慢 SQL 后立刻验证执行计划
第一步：复制面板里显示的完整 SQL（注意别漏掉参数绑定部分）
第二步：粘贴进数据库客户端（如 DBeaver、MySQL CLI），在语句前加 EXPLAIN FORMAT=TREE（MySQL 8.0+）或 EXPLAIN ANALYZE（PostgreSQL）→ 执行
第三步：重点看 rows_examined 和 key 字段；如果 rows_examined 远大于实际返回行数，或 key 为 NULL，说明没走索引——这时候要立刻去对应表补索引，而不是优化 PHP 代码。
⚠️ 注意：面板里看到的 SQL 是带占位符的，例如 WHERE id = :id；真实执行计划必须用替换好参数的语句，否则优化器可能给出错误路径。点开该 SQL 行右侧的「Params」展开项，把实际值手动填进去再 EXPLAIN。
排除干扰：确保只查“真慢”的那条
1. 关闭其他面板干扰：在 config/web.php 的 debug 模块配置中，临时禁用非必要面板，例如：'panels' => ['db' => yii\debug\panels\DbPanel::class, 'profiling' => false, 'logs' => false]；减少数据采集开销，让 DB 面板更专注。
2. 避免事务内批量合并：如果慢查询藏在事务里，DB 面板可能只显示“1 条查询（含 12 条语句）”；这时必须点开该条目 → 查看「Raw SQL」→ 复制全部原始语句 → 分段 EXPLAIN。
3. 确认没绕过 Yii DB 层：如果代码里写了 $pdo = Yii::$app->db->pdo; $pdo->query(...)，这条 SQL 根本不会出现在 DB 面板——所有查询必须走 Yii::$app->db->createCommand() 或 ActiveRecord 方法。
