Yii2 debug模块显示需同时满足三条件:YII_DEBUG为true、客户端IP在allowedIPs白名单中、且仅在YII_ENV_DEV环境下注册;SQL不可见常因enableLogging关闭或绕过Yii DB层;Profiling面板依赖xdebug支持。

yii\debug\Module 是 Yii 应用里最直接、最轻量的性能分析入口——但它默认不显示,也不自动捕获所有瓶颈。真要定位慢点,得先让它“看见”,再让它“看清”。
Debug Toolbar 为什么没出现?三个硬性开关必须同时打开
不是装了模块就生效,而是三者缺一不可:
-
YII_DEBUG必须为true(通常在web/index.php里设置) -
$_SERVER['REMOTE_ADDR']必须落在modules.debug.allowedIPs白名单内,默认只认['127.0.0.1', '::1'];远程调试时加自己 IP,但上线前务必删掉或锁死 - 模块只能在
YII_ENV_DEV下注册;检查config/web.php是否只在开发环境配置了'debug' => ['class' => 'yii\debug\Module']
SQL 面板空着或语句不全?多半是绕过了 Yii 的 DB 层
看到 DbPanel 里只有几条 SQL,或者压根没记录,常见原因如下:
-
yii\db\Connection::enableLogging被手动设为false(默认是true,但有些项目为“省开销”关了) - 用了
$db->pdo直接调用原生 PDO,yii\debug\panels\DbPanel完全捕获不到 - 参数绑定后只显示
:name占位符;要看真实值,得点开每条 SQL 后的「Params」展开项 - 批量操作如
batchInsert()或事务内多语句,可能被合并/截断;这时得配合runtime/logs/app.log查完整日志
Profiling 面板时间不准或空白?xdebug 没配对
这个面板不依赖 Yii 自身逻辑,而是靠 PHP 扩展提供函数级耗时数据:
- 没装
xdebug或tideways,Profiling 就只能显示总请求时间和几个大节点(如Application Init),点不开调用树 - Xdebug 3+ 需开启
xdebug.mode=profile(Yii 2.0.40+ 要求);旧版 Xdebug 2 用xdebug.profiler_enable - 即使开了 xdebug,若
yii\debug\Module配置里把'profiling' => false,面板也会被禁用——别为了“省一点开销”关掉它,排查时它才是关键
比 Debug Toolbar 更深一层:XHProf 和 New Relic 怎么选
Debug Toolbar 适合开发阶段快速定位,但上线后或复杂调用链下,它力不从心:
-
XHProf(或其现代替代tideways)适合代码级分析:能看清楚Post::find()->with('author')里哪个ActiveRecord方法占了 80% 时间,尤其适合查循环嵌套、重复实例化(比如没用asArray()) -
New Relic适合生产环境监控:P95 响应时间、数据库连接池排队、缓存命中率(对应cache组件)、分布式追踪——但需要部署扩展和 license key,开发机上跑不起来 - 二者不互斥:本地用 XHProf 找出
framework/db/Connection.php中某次查询慢的根源,线上用 New Relic 看该接口是否在高并发下恶化
asArray()、with()、enableSchemaCache 这些具体手段去改——工具只是镜子,照得再清,也得动手擦。



















