插件开发指南

你已经做了一个小功能——签到、课表、计算器、社团报名表,什么都行。这份指南讲的是怎么把它变成一个「插件」,让所有校园站都能一键装上。

5 步上架 最快 10 分钟跑通 不需要服务器 不需要数据库
这是什么 你属于哪一类 十分钟跑通 包结构 manifest 字段 访问地址 写页面的硬规则 红线 审核流程 AI 提示词 上架之后 常见问题

1插件到底是什么

一句话:插件就是一个 zip 包,装上去之后你的站点多了一个网址。

不用改任何人的代码,不用管服务器,不用部署。你把文件夹压成 zip 上传,审核通过后,所有申请安装的校园站都会出现你的页面。

装 = 站点多一个网址
比如你的插件叫 kb_tools,装完后访问 https://站点域名/kb_tools.htm 就是你的页面。
卸 = 站点回到原样
文件夹删掉、配置清掉,不留痕迹。所以插件里写的所有东西都必须是「可撤销」的。
一个插件只干一件事
"课表工具"是一个插件,"课表+二手市场+社团"是三个。拆得越干净,越容易过审。

2先确认你属于哪一类

三种类型,难度差一个数量级。建议所有人都从第一种起步。

推荐 · 90% 的人
纯页面插件
只有前端:HTML/CSS/JS。不需要登录、不需要存服务器数据。用浏览器 localStorage 就够。
要改的文件:1 个。
进阶
带配置项的插件
站长能改标题、开关、超链接之类。多写一个配置文件和一个读取函数。
要改的文件:3 个。
需要沟通
要联网 / 要存数据的插件
调用第三方接口、把数据存到站点数据库。这类需要单独评估,先加微信 xbxxh16913 聊。
不建议一上来就做第三种。先把纯页面版本做出来上架,拿到真实用户反馈,再迭代第二版。大多数"需要数据库"的功能,其实用 localStorage 就能跑。

3十分钟跑通第一个插件

别从零建目录。下载起步模板,它已经把该有的东西都写好了,你只换内容。

解压,起名字
myplug 是占位名。你的名字要满足:小写字母开头、3~32 位、只能字母数字下划线。
改名两步:① 文件夹内全量替换 myplug → 你的名字;② 文件夹本身改名。
只有 conf.json 不要动。
换成你的功能
打开 static/app.html,整段删掉,写你自己的网页。它是个普通 HTML 文件,不需要 PHP。
填商店信息
改 manifest.json 里的 name(插件名)、author(你的署名)、brief(一句话介绍)、changelog。版本号从 1.0.0 开始。
本地自检
把 xwplug_check.py 放在插件文件夹旁边(同级),执行:
python xwplug_check.py 你的插件名
它会逐项告诉你哪里会被打回。看到 结果:PASS 再往下走。
打包上传
python xwplug_check.py 你的插件名 --zip
生成 你的插件名-1.0.0.zip,登录 开发者中心 上传。前提是先通过开发者认证(1~2 个工作日)。

4插件包长什么样

zip 里只能有一个顶层文件夹,文件夹名 = 插件名 = manifest 里的 plugid。三者不一致是打回原因第一名。

你的插件名/ ← 顶层唯一目录,名字必须和 plugid 一致 ├── manifest.json 必须:商店信息 + 权限声明 ├── conf.json 必须:站点状态档案,原样保留不要改 ├── install.php 必须:安装时执行一次 ├── unstall.php 必须:卸载时执行一次 ├── icon.png 必须:128×128 ├── hook/ │ └── index_route_case_end.php 必须:把你的网址登记进路由表 ├── route/ │ └── main.php 入口:读配置 → 渲染页面 ├── view/ │ └── main.htm 页面外壳 ├── model/ │ └── main.func.php 工具函数(读配置、转义输出) ├── static/ │ └── app.html ★ 你的功能本体,assets 也放这个目录 └── README.md 可选
文件作用改吗
manifest.json商店里显示的插件名、版本、作者、权限必改
static/app.html你的功能本身必改
hook/…case_end.php把 /你的名字.htm 指向你的路由文件只改名字
route/main.php入口,把配置取出来交给页面一般不动
view/main.htm顶栏 + 全屏容器想改标题栏才动
model/main.func.php读配置、输出转义函数加配置才动
install.php / unstall.php写默认配置 / 清配置加配置才动
conf.json站点记录插件状态的档案不要动
icon.png商店列表图标想换就换
为什么 conf.json 不能动?它里面的 installed / enable 是站点安装后自动置位的。你提前把它们写成 1,装上去就会直接失效。

5manifest.json 逐字段

{ "plugid": "kb_tools", 插件名:小写字母开头,3~32 位,= 文件夹名 "name": "课表工具", 商店显示的名字 "version": "1.0.0", 版本号,更新时递增 "author": "张三", 你的署名,会显示在插件详情页 "brief": "导入课表,生成周视图", 一句话介绍,15~40 字 "permissions": { "db_write": false, 是否写数据库 "file_io": false, 是否写文件 "network": [] 要访问的外部域名,全部写进来 }, "hooks": ["index_route_case_end.php"], "changelog":"1.0.0: 首发" 更新说明,用户能看到 }
字段必填说明
plugid是全局唯一。和你用过的名字冲突会被拒
name是商店里显示的名字,2~12 字最好
version是格式 1.0.0。已上架的插件传新版本号 = 更新
author是写你自己,不要写"官方"
brief建议商店列表就靠这一句让人想点进来
permissions.network视情况代码里出现任何外部域名都必须列进来,否则直接被拒
changelog建议每次更新写一行
能力越大,审核越严。db_write / file_io 填 true 会进人工重点复核。纯页面插件请保持两个 false。

上传时会自动读取包内信息:选好 zip 后,投稿页会把 name → 展示名、brief → 一句话简介、changelog → 更新日志自动填好,仍可手工修改。 简介同时兼容 description 和 Xiuno 标准 conf.json 里的 brief;后台管理员上传只有 conf.json 的官方插件包,也能一键读出名称与简介。

6访问地址是怎么来的

站点路由表靠 hook/index_route_case_end.php 里的一行 case 登记。模板里已经写好了,你只需要改名字:

case 'kb_tools':
    include _include(APP_PATH.'plugin/kb_tools/route/main.php'); break;

改完后,https://站点域名/kb_tools.htm 就是你的页面。case 后面的名字可以比 plugid 短(比如 case 'kbt' → /kbt.htm),但要确认没人用过。

最容易踩的坑:只把 route/main.php 放进 route/ 目录是不会生效的 —— 必须在这个 hook 文件里登记。漏了这一步,访问就是站点首页,看着"像正常",其实是没接上。

7写页面的四条硬规则

① 路径一律用 APP_PATH 拼,不要用 __DIR__

插件文件在运行时的位置和你看到的目录结构不一样,用 __DIR__ 拼出来的路径会指向别的地方,表现就是 500 或白屏。

// 对
include _include(APP_PATH.'plugin/kb_tools/view/main.htm');

// 错(会 500)
include __DIR__.'/../view/main.htm';

② 所有输出都要转义

页面上只要出现来自配置或用户输入的文字,就过一遍转义函数。模板里已经有 myplug_e(),改名后跟着变。

<?php echo kb_tools_e($c['title']); ?>

③ 页面单文件,资源放 static/

HTML/CSS/JS 写在一个文件里最省事;确实要拆,图片和脚本放 static/,用 /plugin/你的名字/static/xx.png 引用。别引外部 CDN,需要引就在 permissions.network 里声明,否则会被当成未声明外联。

④ 页面要能在手机上看

校园站 80% 流量是手机。至少写这个 viewport,别做固定宽度 1200px 的页面:

<meta name="viewport" content="width=device-width, initial-scale=1">

8红线:写了就必被打回

上传后会先过一道自动扫描,下面这些是硬拦,人工看不到就结束了。

类别具体为什么
执行系统命令exec system shell_exec passthru popen proc_open插件跑在别人的站点上,不能碰服务器
动态执行代码eval assert create_function、preg_replace 的 /e
碰系统文件/etc/passwd、.user.ini、authorized_keys、chattr、crontab、创建软链接典型的后门特征
未声明外联代码里出现外部域名,但 network 没写防止偷偷回传数据
收集隐私未经同意读取用户手机号 / 学号 / 位置发现即下架封号
语法错误PHP 语法不过、文件带 BOM 头装上去整站白屏
路径穿越zip 里有 ../ 或绝对路径会覆盖站点其他文件
自检脚本会替你把这些都查一遍,包括 BOM 头和语法错误。上传前跑一次,能省掉一轮打回。
注意:自检 PASS 不等于最终通过 —— 线上还会跑一遍 PHP 语法全量检查与外联声明比对,最终以开发者中心的扫描报告为准;如果打回原因写的是平台侧环境异常(例如影子站不可用),不需要改包,等平台修复后按新版本号重传即可。

9提交后会发生什么

上传 zip
大小上限 5MB。同一个插件重新上传更高版本号即为更新。
自动扫描(1 分钟内)
查结构、语法、红线、外联声明。结果在开发者中心能看到。被拒会写明原因,照着改再传即可。
人工复核(1~2 个工作日)
看你这个插件是干什么的、有没有明显问题、权限声明是否合理。
影子站试装
先在测试站装一遍,确认能打开、不报错、卸载干净。
上架
出现在插件商店,站长可以申请安装。更新走同样流程,但会快很多。

投稿状态怎么看

状态含义你要做什么
待扫描刚上传,排队中等 1 分钟刷新
扫描通过 · 待人工自动检查过了等复核
影子站试装即将上线等
已上架完成可以宣传了
已打回有问题看原因,改完提高版本号重传

10用 AI 写插件:照着这个说

用 AI 最怕的是它"自由发挥"——给你搞出一套完全不属于这个平台的结构。正确用法是:先让它读模板,再让它只改一个文件。

推荐流程

  1. 把起步模板的目录结构截图或文件树贴给 AI,说"这是我必须遵守的结构,不要改"
  2. 让它只输出 static/app.html 一个文件的完整代码
  3. 本地跑一遍自检脚本,把报错原文贴回去让它修
  4. 提审被打回时,把打回原因原样贴给 AI

提示词模板(直接复制改需求)

我要给一个校园社区平台做一个插件页面,请只输出一个完整的 HTML 文件。

【技术约束】
- 单个 .html 文件,CSS 和 JS 全部内联,不引任何外部 CDN、字体、图片外链
- 纯前端,不使用任何后端接口,不发网络请求
- 数据只能存在浏览器 localStorage
- 移动端优先:按 375px 宽度设计,不横向滚动,按钮点击区不小于 40px
- 用系统字体栈,主色 #2f54eb,背景 #fff,正文 #1a1a1a
- 不要用 alert / confirm / prompt,用页面内提示

【功能需求】
(在这里写你要做的东西。越具体越好,比如:
 一个课表工具。用户输入课程名、星期几、第几节、上课地点,
 生成一周课表网格,支持删除单节课,数据存在本地,刷新不丢。
 手机上优先显示"今天"的课,可以切换到整周视图。)

【输出要求】
- 只给完整代码,不要解释,不要分文件
- 代码里不要有 TODO、不要有"此处省略"

等你要改页面外壳时,再问它这个

下面是一个插件的页面外壳文件(view/main.htm),它把一个 iframe 撑满
整个屏幕来加载 static/app.html。我想把顶部工具栏改成:
左边"返回"、中间插件名、右边两个按钮(全屏、分享)。
其余结构不要动,只给我改完的这一份文件,保持原有的变量名不变。

(粘贴 view/main.htm 的内容)
两个提醒:① AI 很爱写 fetch('https://api.xxx.com'),这在纯页面插件里会被拦,直接要求它"不要任何网络请求";② AI 生成的 PHP 经常用 __DIR__ 拼路径、或者自己另起一套目录结构,所以尽量别让它碰 PHP 文件,只让它写 static/app.html。

11上架之后

定价

免费或付费都可以。付费插件由站长下单、平台人工确认到账后自动分发,开发者分成默认 70%(以后台设置为准),结算周期与方式在开发者中心能看到。

更新版本

改完代码把 manifest.json 的 version 提高(如 1.0.0 → 1.1.0),changelog 写清楚改了什么,重新打包上传。已安装的站点可以自助升级。

开发者等级

等级怎么升好处
普通开发者注册并通过认证可投稿,逐个人工复核
认证开发者上架 ≥1 款、评分 ≥4.0、装机 ≥5优先复核,商店显示认证标
金牌开发者上架 ≥3 款、评分 ≥4.5、装机 ≥20免人工复核直通试装,首页推荐位优先

什么情况会被下架

12常见问题

我只会前端,不会 PHP,能做吗?
能。纯页面插件只需要改 static/app.html 一个文件,其余照抄模板。
装上去打开是站点首页,不是我的页面?
两种可能:① hook/index_route_case_end.php 里没登记你的 case;② 登记的名字和文件夹名不一致。
打开 500 报错?
九成是路径问题。检查有没有用 __DIR__ 拼路径,改成 APP_PATH.'plugin/你的名字/...'。
可以用 jQuery / Vue / Tailwind 吗?
用 CDN 会被当作未声明外联,需要写进 permissions.network,且会变慢。建议直接写原生 JS + CSS,模板里的样式就是手写的,可以拿来改。
插件能读到用户是谁吗?
纯页面插件读不到,也不需要。需要登录态的功能属于进阶类型,先联系我们再评估。
一次能传几个?
每天最多 10 个包,同时在审的最多 12 个。别刷。
可以用 AI 生成吗?
可以,也不反对。但你要能为提交的代码负责——审核看的是结果,出问题也找作者。
审核被打回会告诉我原因吗?
会。开发者中心能看到具体条目,照着改、提高版本号重传即可。
校园站插件商店 · 开放生态
还有问题?加微信 xbxxh16913,或到 开发者中心 提交申请