字段一览
| 字段 | 必填 | 说明 |
| --- | :---: | --- |
| slug | ✅ | 插件标识(小写字母/数字/_/-,2~40 位),= 目录名,市场唯一 |
| name | ✅ | 显示名称(≤40 字,可中文) |
| version | ✅ | 语义化版本,如 1.0.0;发布新版本必须递增 |
| author | ✅ | 作者 / 团队 |
| description | ✅ | 一句话说明(市场列表展示) |
| homepage | | 项目主页或仓库地址 |
| license | | 开源协议,如 MIT / Apache-2.0 |
| requires | | 依赖:{ "core": ">=1.0.0", "php": ">=7.4", "plugins": {"other_slug": ">=1.0.0"} } |
| capabilities | | 能力声明,见下表;只声明真正用到的 |
| priority | | 加载优先级 1~99,数字越小越先加载(默认 50) |
| settings | | 后台可视化设置项数组 |
| admin | | 后台页展示信息:{ "title": "…", "icon": "fa-music", "desc": "…" } |
| front | | 前台页说明:{ "index": "音乐库页面 /music.php" } |
| hooks | | 用到的钩子名数组(仅用于说明/展示) |
| lifecycle | | 生命周期回调:{ "install": "lifecycle.php:onInstall", "uninstall": "lifecycle.php:onUninstall" } |
| cron | | 定时任务说明(真正注册用 registerPluginCron()) |
能力(capabilities)
平台会取交集:声明了才拿得到,多声明会被记录在插件信息里(审核时也会看)。
| 能力 | 你能用的东西 |
| --- | --- |
| admin_ui | registerAdminPage() 后台页面 |
| front_ui | registerFrontView()、addShortcode()、渲染注入 |
| db | pluginCreateTable() / pluginTableName() / 直接用 getDB() 建自己的表 |
| files | pluginUploadDir() 插件私有上传目录 |
| http | pluginHttp() 带超时与熔断的外部请求 |
| mail | 调用核心的邮件发送能力(需站长已配置 SMTP) |
设置项(settings)
json
"settings": [
{ "key": "enabled", "label": "启用", "type": "switch", "default": "1" },
{ "key": "title", "label": "标题", "type": "text", "default": "公告" },
{ "key": "content", "label": "内容", "type": "textarea","default": "" },
{ "key": "max", "label": "最多显示", "type": "number", "default": "5" },
{ "key": "color", "label": "配色", "type": "select", "default": "blue",
"options": { "blue": "信息蓝", "green": "成功绿", "red": "警示红" } }
]> 升级后新增的设置项,即使站长还没保存过,也会自动读到清单里的 default(后台设置页还有「恢复默认值」按钮)。
读取与保存:
php
$v = pluginSetting('my_plugin', 'title', '默认值'); // 单个
$all = pluginSetting('my_plugin'); // 全部
pluginSaveSettings('my_plugin', ['title' => '新标题']); // 保存(后台设置表单会自动调它)> switch 存的是 '1' / '0',判断请用 pluginSetting(...) === '1' 或 !empty(),不要直接当布尔用字符串比较。
生命周期(lifecycle.php)
php
<?php
function onInstall($db) {
// 建表(幂等,别用 DROP)
pluginCreateTable('my_plugin', 'logs',
'id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT, created_at TEXT');
}
function onUninstall($db) {
// 卸载时清理自己的表与设置(平台也会调用,但写清楚更保险)
try { $db->exec('DROP TABLE IF EXISTS ' . pluginTableName('my_plugin', 'logs')); } catch (Throwable $e) {}
pluginClearSettings('my_plugin');
}声明方式:
json
"lifecycle": { "install": "lifecycle.php:onInstall", "uninstall": "lifecycle.php:onUninstall" }