DEVELOPER GUIDE

插件制作教程

从扩展包、插件中心、主题、字体到系统升级包,按这里的格式制作,上传后会自动检测兼容性;检测通过才会投入使用。

当前站点 v6.25.225 · 2026-11-15 更新

〇、上传检测总规则

后台的插件中心、扩展管理、字体设置、主题管理、系统升级都会先自动检测。检测不通过的包会被直接拒绝,不会写入站点;检测通过的包才会安装或升级,并立即投入使用。

结构检测ZIP 是否能正常解压、是否有非法路径、软链接、压缩炸弹。
类型检测文件扩展名是否在白名单内,是否夹带 config.php、.htaccess、可执行脚本。
语法检测所有 PHP 文件先做语法解析,避免半截代码或损坏文件。
兼容检测PHP 版本、站点版本、主题标识、字体文件头是否匹配。
危险调用检测插件不允许删除文件、写文件、执行命令、直接改数据库。
运行时检测系统升级写入文件后会启动一次新版本引导检查,失败自动回滚。

重要:不要用 ZIP 工具给站点根目录整体打包后直接当升级包。升级包必须带清单、必须去掉 config.php 和 data/uploads/storage。插件包也不要包含站点核心文件。

一、扩展中心插件制作

扩展中心上传的包和插件中心使用同一套安装器:支持 ZIP 插件包,也支持单个 JSON 文件。最轻量的做法是制作 JSON,把一段 HTML 挂到首页钩子上。

1. JSON 扩展包结构

{
  "name": "侧边小贴士",
  "slug": "side-tip",
  "version": "1.0.0",
  "description": "首页底部显示一句提示",
  "hook": "home_bottom",
  "html": "<div class=\"side-tip\">今天也要记得喝茶。</div>"
}

字段说明:name 是显示名称;slug 是唯一标识,只能使用英文、数字、短横线;version 不超过 20 个字符;description 不超过 200 字;hook 必须是允许的钩子;html 是前台显示内容,最多 200KB。

2. ZIP 扩展包结构

welcome-bar.zip
├── plugin.json
├── plugin.php
└── assets/
    └── welcome.css

ZIP 根目录或唯一一层文件夹内必须同时存在 plugin.json 和 plugin.php。可选放置 CSS、JS、图片,但只允许常见的静态资源类型。

3. 上传与启用

进入后台「扩展管理」→ 上传自定义扩展包 → 选择 ZIP 或 JSON → 点击上传。检测通过后自动安装并启用,扩展中心会显示入口;也可以在「插件中心」停用或删除。

扩展中心是给访客看的入口卡片;插件则是挂在页面钩子上的内容。同一个包会同时出现在两个后台的插件记录里。

二、插件中心插件制作

插件中心适合做“在前台某个位置输出内容”的轻量插件。插件不直接修改站点核心文件,只通过钩子插入页面。

1. plugin.json 清单

{
  "name": "首页欢迎条",
  "slug": "welcome-bar",
  "version": "1.0.0",
  "description": "在首页顶部显示一条欢迎提示",
  "hook": "home_top",
  "php_min": "7.4",
  "app_min": "6.24.0"
}
字段必填说明
name是插件名称,最多 60 字
slug是英文、数字、下划线、短横线,最多 40 位;同名会被覆盖更新
version是版本号,例如 1.0.0
description否简介,最多 200 字
hook是见下方钩子表
php_min / php_max否要求 PHP 版本;默认 7.4 起
app_min / app_max否要求站点版本;不填则不限制

2. plugin.php 写法

<?php
// 插件入口文件,只能通过 plugin_register 挂载到允许的钩子
plugin_register('home_top', function () {
    echo '<div class="welcome-bar">欢迎来到木漏茶室</div>';
});

插件入口必须调用 plugin_register('钩子名', function () { ... });。允许的钩子:

home_top 首页顶部 home_quote 每日一言下方 home_bottom 首页底部 home_popup 首页弹窗 layout_footer 全站页脚

3. 插件包目录

my-plugin.zip
└── my-plugin/
    ├── plugin.json
    ├── plugin.php
    └── assets/
        ├── logo.png
        └── plugin.css

为了不破坏站点,插件代码不允许出现删除/写入文件、执行系统命令、引入包外文件、直接操作数据库的调用。插件只负责输出展示内容;需要复杂功能时,请做成系统升级包。

4. 上传

后台「插件中心」→ 上传插件包 → 检测通过后自动安装并启用;失败会显示具体原因,文件不会写入正式插件目录。

三、主题制作

主题是一个 CSS 文件。制作时先确定唯一的主题标识(例如 tea_blue),CSS 必须全部包在这个选择器里,才能只影响该主题。

1. 最小可用主题

html[data-theme="tea_blue"] {
  --bg: #f4fbff;
  --card: #ffffff;
  --text: #17384a;
  --accent: #2f8fbf;
  --accent-2: #8dc9e6;
}
html[data-theme="tea_blue"] body {
  background: linear-gradient(180deg, #f4fbff, #e8f5fc);
}
html[data-theme="tea_blue"] .site-header {
  background: rgba(255,255,255,.86);
}

标识只能是 2–32 位英文、数字、下划线或短横线;CSS 里必须出现 html[data-theme="你的标识"],否则上传会被拒绝,因为主题不会生效。

2. 常用变量

主题可以覆盖站点的 CSS 变量:--bg 页面底色、--card 卡片底色、--text 主文字、--muted 次要文字、--accent 主色、--accent-2 辅助色、--line 边框色。也可以在主题标识下写具体组件样式,例如 html[data-theme="tea_blue"] .site-header { ... }。

3. 安全限制

不允许脚本、@import 外链、expression()、HTML 标签和超出 2MB 的文件;CSS 括号必须成对。建议先在桌面和手机上各看一次,浅色主题不要用纯白字,深色主题不要用深色字。

4. 上传

后台「主题管理」→ 填写主题名称与标识 → 拖入 CSS → 上传并加入主题库。检测通过后会出现在前台主题面板;勾选“强制主题”可让访客不能覆盖。

四、字体制作

字体上传的是单个字体文件,不是 ZIP。支持 woff2、woff、ttf、otf,单个文件不超过 20MB。

1. 选文件与命名

优先使用 woff2(体积小、网页加载快);ttf/otf 兼容性好但体积更大。字体名称填中文可读名,例如“黄霄云汉仪体”,不要填文件名乱码。

2. 版权与完整性

只上传你有权在网站使用的字体,不要上传来历不明的商用字体。文件必须是真实字体:系统会检查 wOF2、wOFF、OTTO、true、ttcf 或 TrueType 文件头,伪装成字体的图片、脚本、压缩包会被拒绝。

3. 上传与启用

后台「字体设置」→ 填名称 → 拖入字体文件 → 上传并加入字体库 → 点“启用”。启用后全站前台和后台统一生效;替换字体时旧文件会被清理。

五、系统升级包制作

系统升级包是一个完整站点源码 ZIP,用来把整站升级到新版本。它比普通插件更严格:必须带清单、必须版本更高、必须能通过新版本引导检查。

1. 清单文件

在升级包根目录放 komorebi-upgrade.json:

{
  "type": "komorebi-upgrade",
  "name": "木漏茶室 v6.25.47 系统升级包",
  "version": "6.25.47",
  "app_min": "6.24.0",
  "app_max": "6.25.99",
  "php_min": "7.4",
  "php_max": "8.3",
  "changelog": "新增某项功能,修复若干问题。",
  "delete": ["pages/old_page.php"]
}
字段说明
type固定写 komorebi-upgrade
name升级包显示名称,最多 80 字
version目标版本,必须高于当前版本
app_min / app_max允许从哪个站点版本升级;当前版本不在范围内会拒绝
php_min / php_max要求 PHP 版本;不填 php_max 表示不限制上限
changelog升级说明,会显示在升级记录里
delete可选,升级后要删除的旧文件相对路径

2. 目录要求

komorebi-upgrade.zip
├── komorebi-upgrade.json
├── index.php
├── inc/
├── pages/
├── admin/
├── assets/
├── README.md
└── sw.js

必须包含:index.php、inc/bootstrap.php、inc/helpers.php、inc/db.php、pages/admin.php、assets/css/app.css。只允许这些顶层目录:assets、inc、pages、admin、plugins;以及 index.php、api.php、manifest.php、robots.txt、rss.php、sitemap.php、sw.js、README.md。

绝对不要打包:config.php、data/、uploads/、storage/、install.php、.htaccess、.user.ini、.git/。包含这些的包会被直接拒绝。

3. 版本一致性

源码里的 inc/bootstrap.php 必须把自己的 APP_VERSION 改成与清单 version 完全一致,例如都写 6.25.33。清单说 6.25.32 但源码还是 6.24.0,会被判为不一致而拒绝。

4. 制作流程

  1. 复制当前站点完整源码到工作目录,不要复制 config.php、data、uploads、storage。
  2. 完成代码修改,跑一遍所有 PHP 文件的语法检查;建议先在测试站完整点一遍首页、帖子、个人主页、后台。
  3. 修改 inc/bootstrap.php 的 APP_VERSION、sw.js 缓存版本、README 版本说明。
  4. 在根目录写 komorebi-upgrade.json,把 app_min 设为当前线上版本,app_max 设为当前小版本范围。
  5. 把源码和清单打成 ZIP,确认解压后第一层就能看到清单与 index.php;不要多套一层无意义的文件夹。
  6. 到后台「系统升级」拖入 ZIP。系统会先检测,再自动备份旧版核心文件、应用新文件并做一次运行时引导检查。

5. 升级后的行为

检测通过后自动投入使用,并在 storage/upgrades/ 保留核心文件备份。升级记录可以点“回滚文件”恢复升级前源码;如果新版本改了数据库结构,回滚源码后还需要去「备份恢复」恢复对应时间点的数据库备份。

升级过程会短暂打开维护模式,完成后自动恢复原来的维护设置。升级包不要依赖某个具体主机路径,也不要在包里写死域名。

六、常见拒收原因

ZIP 路径穿越包含 ../、绝对路径或软链接,直接拒绝。

夹带配置与数据升级包包含 config.php、data、uploads、storage、install.php,直接拒绝。

版本不兼容PHP 版本不满足、站点版本不在 app_min/app_max 范围、升级包版本不高于当前版本。

源码版本不一致清单 version 与 inc/bootstrap.php 的 APP_VERSION 不一样。

语法错误任意 PHP 文件解析失败,整包拒绝,不会安装一半。

插件越权插件代码出现删除、写入、执行命令、直接改数据库、引入包外文件,整包拒绝。

主题不生效CSS 缺少 html[data-theme="标识"],或包含脚本/外链导入。

字体伪装文件头不是真实字体,或扩展名不在 woff2/woff/ttf/otf 内。

上传失败时先看红色提示的具体原因;修正后重新打包再传。系统不会把“没通过检测”的包偷偷放进站点。

主题