生命周期回调
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,不要指望平台兜底 —— 平台会兜,但你的插件会被熔断。