校园站插件开发指南
本文共计7321个字,预计阅读时长29.3分钟。
目录
- 1. 1插件到底是什么
- 2. 2先确认你属于哪一类
- 3. 3十分钟跑通第一个插件
- 4. 4插件包长什么样
- 5. 5manifest.json 逐字段
- 6. 6访问地址是怎么来的
- 7. 7写页面的四条硬规则
- 7.1. ① 路径一律用 APP_PATH 拼,不要用 __DIR__
- 7.2. ② 所有输出都要转义
- 7.3. ③ 页面单文件,资源放 static/
- 7.4. ④ 页面要能在手机上看
- 8. 8红线:写了就必被打回
- 9. 9提交后会发生什么
- 9.1. 投稿状态怎么看
- 10. 10用 AI 写插件:照着这个说
- 10.1. 推荐流程
- 10.2. 提示词模板(直接复制改需求)
- 10.3. 等你要改页面外壳时,再问它这个
- 11. 11上架之后
- 11.1. 定价
- 11.2. 更新版本
- 11.3. 开发者等级
- 11.4. 什么情况会被下架
- 12. 12常见问题

1插件到底是什么
一句话:插件就是一个 zip 包,装上去之后你的站点多了一个网址。
不用改任何人的代码,不用管服务器,不用部署。你把文件夹压成 zip 上传,审核通过后,所有申请安装的校园站都会出现你的页面。
kb_tools,装完后访问 https://站点域名/kb_tools.htm 就是你的页面。2先确认你属于哪一类
三种类型,难度差一个数量级。建议所有人都从第一种起步。
要改的文件:1 个。
要改的文件:3 个。
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 再往下走。4插件包长什么样
zip 里只能有一个顶层文件夹,文件夹名 = 插件名 = manifest 里的 plugid。三者不一致是打回原因第一名。
| 文件 | 作用 | 改吗 |
|---|---|---|
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 |
商店列表图标 | 想换就换 |
installed / enable 是站点安装后自动置位的。你提前把它们写成 1,装上去就会直接失效。5manifest.json 逐字段
| 字段 | 必填 | 说明 |
|---|---|---|
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 里有 ../ 或绝对路径 |
会覆盖站点其他文件 |
注意:自检 PASS 不等于最终通过 —— 线上还会跑一遍 PHP 语法全量检查与外联声明比对,最终以开发者中心的扫描报告为准;如果打回原因写的是平台侧环境异常(例如影子站不可用),不需要改包,等平台修复后按新版本号重传即可。
9提交后会发生什么
投稿状态怎么看
| 状态 | 含义 | 你要做什么 |
|---|---|---|
| 待扫描 | 刚上传,排队中 | 等 1 分钟刷新 |
| 扫描通过 · 待人工 | 自动检查过了 | 等复核 |
| 影子站试装 | 即将上线 | 等 |
| 已上架 | 完成 | 可以宣传了 |
| 已打回 | 有问题 | 看原因,改完提高版本号重传 |
10用 AI 写插件:照着这个说
用 AI 最怕的是它"自由发挥"——给你搞出一套完全不属于这个平台的结构。正确用法是:先让它读模板,再让它只改一个文件。
推荐流程
- 把起步模板的目录结构截图或文件树贴给 AI,说"这是我必须遵守的结构,不要改"
- 让它只输出
static/app.html一个文件的完整代码 - 本地跑一遍自检脚本,把报错原文贴回去让它修
- 提审被打回时,把打回原因原样贴给 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 的内容)
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常见问题
static/app.html 一个文件,其余照抄模板。hook/index_route_case_end.php 里没登记你的 case;② 登记的名字和文件夹名不一致。__DIR__ 拼路径,改成 APP_PATH.'plugin/你的名字/...'。permissions.network,且会变慢。建议直接写原生 JS + CSS,模板里的样式就是手写的,可以拿来改。