跳到主要内容
万能墙开放平台
插件开发教程

生命周期、日志与熔断

全部内容基于万能墙真实的插件平台(清单 + 钩子 + 接口 + 后台页 + 数据 + 定时任务),示例可直接复制运行。

生命周期回调

plugin.json:

json
"lifecycle": { "install": "lifecycle.php:onInstall", "uninstall": "lifecycle.php:onUninstall" }

| 时机 | 什么时候跑 | 建议做什么 |

| --- | --- | --- |

| install | 首次安装、以及每次覆盖更新后 | 建表、加列、补默认设置 —— 必须幂等,它就是你的"迁移入口" |

| uninstall | 站长卸载时 | 删表、删设置、删上传文件 |

| enable | 插件被启用时 | 预热缓存、补一次数据(失败会阻止启用) |

| disable | 插件被停用前 | 清理临时状态(报错只记日志,不阻止停用) |

文件写法有四种,随便挑一种(清单里对应地写):

php
// ① 声明全局函数 —— 清单写 "lifecycle.php:onInstall"
function onInstall($ctx) { /* ... */ }

// ② 直接 return 一个回调 —— 清单写 "lifecycle.php"
return function ($ctx) { /* ... */ };

// ③ return 事件表 —— 清单写 "lifecycle.php"
return ['install' => fn($ctx) => true, 'uninstall' => fn($ctx) => true];

// ④ 纯顶层代码(老写法)—— 清单写 "lifecycle.php",载入即执行
pluginCreateTable('my_plugin', 'logs', '...');

> 平台会把回调文件里的函数名自动加上插件前缀再执行,所以多个插件同时安装/卸载也不会撞名;

> 你写代码时不用管这件事,直接用 onInstall 这样的名字即可。

> 回调里的 $ctx 含 slug / db / manifest / event。

日志

php
pluginLog('my_plugin', 'info',  '插件已加载');
pluginLog('my_plugin', 'warn',  '外部接口超时,已跳过本次同步');
pluginLog('my_plugin', 'error', '写入失败:' . $e->getMessage());

$logs = pluginLogs('my_plugin', 50);   // 后台「插件日志」页也能看
pluginLogsClear('my_plugin');          // 清空

不要把用户隐私(手机号、身份证、密码、聊天原文)写进日志。

故障熔断

  • 同一插件在 1 小时内累计 10 次故障(阈值可由站长配置),会被标记 faulted 并暂停加载;
  • 后台插件页可看到故障原因与次数,支持「清除熔断」;
  • 站长遇到插件冲突时可用安全模式(?no_plugins=1 带安全钥匙)让所有插件不加载,先救站再排查。

因此:任何钩子里的异常都要自己 try/catch,不要指望平台兜底 —— 平台会兜,但你的插件会被熔断。