自定义Debug面板需满足两条件：类继承yii\debug\Panel且getSummary()、getDetail()均返回非空HTML；同时确保模块启用、IP允许、路径可加载、日志目录可写。
Debug面板里加自定义面板，核心就两步：注册+渲染
Yii2的yii\debug\Module允许通过panels配置注入自定义面板类，但很多人卡在“注册了没显示”——根本原因是没同时满足两个条件：类必须继承yii\debug\Panel，且getSummary()和getDetail()方法不能空返回或抛异常。
常见错误现象：debug toolbar上看不到新面板图标；点开debug页面后报Call to a member function getSummary() on null；或者面板显示但内容空白。
- 自定义类必须放在可自动加载路径下（如
@app/components/debug/MyPanel.php），并确保命名空间正确 -
getSummary()必须返回一段HTML字符串（哪怕只是<span>My</span>），否则toolbar图标不渲染 -
getDetail()返回的HTML会被放进tab页，若含JS需注意执行时机——debug页面是AJAX加载的，直接写<script>可能不执行 - 配置写在
modules['debug']['panels']里，键名就是面板ID（如'mypanel'），会自动映射到toolbar图标文字
工具栏按钮怎么加？靠Toolbar类的addButton()
默认toolbar只显示内置面板入口，想加个“查看缓存键”或“触发测试任务”的按钮，得自己扩展yii\debug\Toolbar行为。但别动vendor里的源码——正确做法是用modules['debug']['class']指向一个继承自yii\debug\Module的子类，在init()里调用$this->on(Module::EVENT_AFTER_INIT, [...])来注入按钮逻辑。
使用场景：比如你想在toolbar右侧加个Flush Cache按钮，点击后清空当前环境的cache组件。
- 按钮HTML由
yii\debug\Toolbar::addButton()生成，传入数组包含'label'、'url'、'options'（支持class、data-method等） -
url最好指向debug模块下的action（如['debug/my-flush']），避免跨模块路由问题 - 注意CSRF：debug模块默认禁用CSRF验证，但如果手动启用了
enableCsrfValidation = true，按钮请求会400，得加data-csrf属性 - 按钮样式受限于debug自带CSS，加
class="btn btn-xs btn-default"最稳妥，别用btn-primary——颜色会被覆盖
自定义面板数据采集时机不对？看init()和save()的分工
很多面板显示“无数据”，其实是把耗时操作（比如查数据库、读文件）写进了init()——这个方法在每次请求初始化模块时就执行，但debug数据只在调试开启且响应结束前才真正收集。正确逻辑是：在init()里只做轻量准备（如绑定事件），把实际采集放到save()里。
性能影响明显：如果在init()里执行file_get_contents('/var/log/app.log')，每个请求都会触发，不管debug是否开启。
-
init()适合注册Application::EVENT_BEFORE_REQUEST这类钩子，为后续采集埋点 -
save()才是数据落盘时刻，此时可安全访问$this->data并赋值，它最终被序列化进debug日志文件 - 如果要采集响应头之类的数据，记得在
save()里通过Yii::$app->response取，别在init()里提前读——那时response还没生成 - 避免在
save()里做阻塞操作，debug日志写入本身是同步的，慢操作会拖慢整个响应
为什么本地能跑，上线就404或白屏？检查allowedIPs和enabled
自定义面板代码没问题，但线上死活不显示，大概率是debug模块压根没启用。Yii2 debug默认只对localhost和127.0.0.1开放，生产环境IP不在allowedIPs里，整个debug模块会被跳过——包括你的面板注册逻辑。
另一个坑是enabled配置项被设为false，或者用YII_DEBUG环境变量控制时，忘了在web服务器里透传该变量。
-
allowedIPs必须显式包含部署机真实IP（如['192.168.1.100', '::1']），不能只写['*']——Yii2不支持通配符 - 确认
YII_DEBUG在PHP里是true：var_dump(YII_DEBUG);比看nginx配置更可靠 - debug日志存在
@runtime/debug目录下，如果该目录不可写，面板可能静默失败，连错误提示都不出 - 浏览器F12看Network，过滤
debug/default/toolbar，如果返回404，说明模块路由根本没注册——检查modules['debug']是否在正确的应用配置层级（通常是web.php，不是main.php）
最麻烦的不是写错代码，而是debug模块在某个环节被绕过了——它不报错，只沉默。盯住@runtime/debug有没有新文件生成，比看页面更直接。
