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

plugin.json 字段与自检规则(由核心契约生成)

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

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&section=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 提供独立页面。