plugin.json 字段(由契约生成)
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | :---: | --- |
| slug | string | ✔ | 插件唯一标识,必须与目录名一致;小写字母/数字/下划线或短横线,2~40 位 |
| name | string | ✔ | 中文名(后台列表与市场展示) |
| version | string | ✔ | 语义化版本 x.y.z,每次提交市场必须递增 |
| author | string | ✔ | 作者名(市场展示与审核联系) |
| description | string | ✔ | 一句话说明这个插件做什么(写清功能,别写"暂无") |
| requires | object | | 依赖声明:core(本站核心版本规则,用 GET /api?action=plugin_contract 查 core_version;不确定就写 >=1.0.0)、php(如 >=7.4)、plugins(依赖的其它插件 slug => 版本规则) |
| capabilities | array | ✔ | 能力声明,取值见「能力」一节;不声明就用不了对应能力(会被平台拒绝注册) |
| priority | number | | 加载顺序,1~99,数字越小越先加载;默认 50 |
| settings | array | | 设置项声明(后台自动渲染表单):key / label / type / default / options / help |
| hooks | array | | 你监听的钩子名(会显示在后台插件详情里,方便排查;名单必须在契约里存在) |
| admin | object | | 后台页声明:title / icon(FontAwesome 类名)/ desc / perm |
| front | object | | 前台视图声明:视图名 => 说明,如 index。访问入口 /plugin.php?p=<slug>&view=index |
| cron | object | | 定时任务声明(说明用):任务键 => 间隔秒数 |
| lifecycle | object | | 生命周期入口:install / upgrade / enable / disable / uninstall => "文件名:函数名"。覆盖更新且版本号变化时,平台会额外触发 upgrade(回调上下文带 from/to) |
| data_collection | string|array | | 数据收集声明(自述):插件会收集/上报哪些数据、发往哪里。声明了 db/http/mail 等能力时强烈建议填写——市场详情页会原样展示给使用者,未声明时会提示"开发者未声明数据收集范围" |
设置项类型
text—— 单行文本textarea—— 多行文本switch—— 开关("1" / "0")number—— 数字select—— 下拉选择(配 options:值 => 显示名)
生命周期
事件:install enable disable uninstall
支持四种写法:
file:func—— lifecycle.php:onInstall —— 最常用,文件里写 function onInstall($ctx)return_callable—— return function ($ctx) { ... }; —— 顶层直接 return 一个闭包return_array—— return ['install' => function ($ctx) {}, 'uninstall' => function ($ctx) {}]; —— 一个文件托管多个事件top_level—— 顶层代码(文件被加载即执行)—— 简单场景可用
上下文:{ slug, db, manifest, event }:slug 插件标识、db 数据库连接、manifest 已解析清单、event 当前事件名
- install 在「首次安装」和「上传新版本覆盖」时都会执行,适合建表/写默认设置,必须幂等。
- uninstall 默认会被平台调用一次以清理数据表(后台卸载时勾选"保留数据"则跳过)。
- 同一请求里可能连续处理多个插件的生命周期,所以不要依赖函数名全局唯一——平台会自动加前缀。
自检规则
上传前跑 php backend/plugin_lint_cli.php <插件目录|zip>,出现的就是这些编号:
| 规则 | 级别 | 含义 |
| --- | :---: | --- |
| MANIFEST_MISSING | error | 缺少 plugin.json(或 JSON 解析失败) |
| MANIFEST_FIELD | error | 缺少必填字段 / 字段类型不对 |
| SLUG_MISMATCH | error | 清单里的 slug 与目录名不一致 |
| VERSION_FORMAT | error | version 不是 x.y.z 形式 |
| CAP_UNKNOWN | error | capabilities 里出现平台不认识的能力 |
| HOOK_UNKNOWN | error | 代码里监听/触发的钩子不在平台契约里(多半是拼错了) |
| ROUTE_INVALID | error | 接口名不合法(需 2~40 位小写字母/数字/下划线) |
| ROUTE_NO_DESC | warn | 注册接口没写 desc 说明 |
| ROUTE_NO_PARAMS | warn | 写接口没写 params 且未声明 no_params |
| PHP_SYNTAX | error | PHP 语法错误 |
| FORBIDDEN_CALL | error | 出现被禁止的函数(eval/exec/system/shell_exec/passthru/popen/proc_open) |
| READ_ENV | error | 试图读取站点配置文件(.env.php) |
| TOUCH_CORE | error | 试图改写核心表或核心开关(PLUGINS_ENABLED 等) |
| CAP_MISSING | warn | 用了某项能力却没在清单里声明 |
| SETTING_UNDECLARED | warn | 代码里读了没在清单里声明的设置项 |
| ASSET_MISSING | warn | 引用的 assets/ 文件不存在 |
| ASSET_EXT | warn | assets/ 里有平台不放行的扩展名 |
| CALLBACK_ARGS | warn | 渲染区域回调的附加参数没给默认值(调用点少传参数会报 ArgumentCountError) |
| LIFECYCLE_MISSING | error | 清单声明了生命周期入口,但文件或函数不存在 |
| NO_PLUGIN_PHP | error | 缺少入口文件 plugin.php |
| README_MISSING | info | 建议放一份 README.md 说明功能与设置 |
静态资源与上限
- 资源目录:
assets/,放行扩展名:css,js,mjs,png,jpg,jpeg,gif,webp,svg,ico,woff,woff2,ttf,otf,json,txt,map - 其它扩展名(含 php/phtml/html/js 之外的可执行类)一律 404;目录穿越与符号链接会被拒绝。
- 缓存:带 ETag/Last-Modified,命中 304;响应头 Cache-Control: max-age=604800。改文件后建议在 URL 上带版本参数(pluginAssetUrl 会用插件版本号)。
- 安装包不超过 8MB(含所有文件)
- 单个设置值建议不超过 64KB(大文件请走 pluginUploadDir())
- pluginHttp() 默认超时 5 秒,单次响应体上限 1MB
- 日志按插件保留最近 200 条
- 1 小时内同一插件累计 10 次异常会被自动熔断(停用并在后台标注原因)
- 自建表统一用 pluginTableName() 生成,禁止直接拼核心表名(users / posts / comments 等)
常见问题
Q:我不懂 PHP 框架,能写吗?
A:插件就是一个普通 PHP 文件 + 一个 plugin.json 清单,不需要框架知识;用脚手架生成骨架后改里面标记的位置即可。
Q:怎么知道有哪些钩子能用?
A:看文档的「扩展点清单」,或直接请求 GET /api?action=plugin_contract§ion=hooks 拿到机器可读的完整列表(含参数与示例)。
Q:改了代码怎么生效?
A:插件每个请求都重新加载,改完文件刷新页面即可;改 plugin.json 后后台插件列表会自动刷新(平台带缓存指纹)。
Q:插件能在别的万能墙站点用吗?
A:能。只要对方核心版本满足 requires.core,且你只用了契约里的钩子与函数。
Q:怎么本地验证?
A:用 php backend/plugin_new_cli.php 生成骨架(自带自检),或对已有目录跑 php backend/plugin_lint_cli.php backend/plugins/<slug>。
Q:插件崩了会影响整站吗?
A:不会。平台的钩子回调有异常隔离,出错只记日志并计数,1 小时内同类异常累计 10 次会自动熔断停用该插件。
Q:能改核心页面结构吗?
A:不能直接改核心文件;请用渲染区域过滤器往页面注入 HTML,或用 registerFrontView 提供独立页面。