木漏茶室源码下载中心
整站 PHP 源码:可浏览文件、复制路径、下载单文件或打包 ZIP。
发布版本 v6.25.232
升级后自动生成独立源码包,下载中心只发送这份冻结包
已排除 config.php / 用户数据 / 上传文件 / 升级备份
COMMUNITY DEPLOYMENTS
已经跑起来的木漏茶室
从源码下载中心下载、完成安装并回传验证的站外站点。每个站点只计 1 次部署下载量;已记录站点会实时读取名称、版本、Logo 与在线状态,本机、内网和证书异常站点无法完成回传。
实时检测
2
个站点已部署
木
木漏茶室
mlcs.xnn.lol · v6.25.232
访问 ↗
2026.11.21
在线
木
木漏茶室
mlcs.nbnb.mom · v6.25.232
访问 ↗
2026.11.20
在线
已展示全部 2 个站点。
pages/tutorial.php
16.5 KB · 发布包 v6.25.232
<?php
/**
* 插件制作教程:扩展中心插件、插件中心、主题、字体、系统升级包
*/
$activeTab = (string) input('tab', 'extension');
$pluginJson = <<<'CODE'
{
"name": "首页欢迎条",
"slug": "welcome-bar",
"version": "1.0.0",
"description": "在首页顶部显示一条欢迎提示",
"hook": "home_top",
"php_min": "7.4",
"app_min": "6.24.0"
}
CODE;
$pluginPhp = <<<'CODE'
<?php
// 插件入口文件,只能通过 plugin_register 挂载到允许的钩子
plugin_register('home_top', function () {
echo '<div class="welcome-bar">欢迎来到木漏茶室</div>';
});
CODE;
$extensionJson = <<<'CODE'
{
"name": "侧边小贴士",
"slug": "side-tip",
"version": "1.0.0",
"description": "首页底部显示一句提示",
"hook": "home_bottom",
"html": "<div class=\"side-tip\">今天也要记得喝茶。</div>"
}
CODE;
$themeCss = <<<'CODE'
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);
}
CODE;
$upgradeJson = <<<'CODE'
{
"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"]
}
CODE;
$GLOBALS['PAGE'] = 'tutorial';
render_header('插件制作教程');
?>
<section class="ext-hero small tutorial-hero">
<span class="hero-kicker">DEVELOPER GUIDE</span>
<h1>插件制作教程</h1>
<p>从扩展包、插件中心、主题、字体到系统升级包,按这里的格式制作,上传后会自动检测兼容性;检测通过才会投入使用。</p>
<span class="tutorial-updated">当前站点 v<?= e(APP_VERSION) ?> · 2026-11-15 更新</span>
</section>
<div class="tutorial-layout">
<nav class="tutorial-nav" aria-label="教程目录">
<a href="#rules" class="<?= $activeTab === 'rules' ? 'on' : '' ?>">〇、上传检测总规则</a>
<a href="#extension" class="<?= $activeTab === 'extension' ? 'on' : '' ?>">一、扩展中心插件</a>
<a href="#plugin" class="<?= $activeTab === 'plugin' ? 'on' : '' ?>">二、插件中心插件</a>
<a href="#theme" class="<?= $activeTab === 'theme' ? 'on' : '' ?>">三、主题制作</a>
<a href="#font" class="<?= $activeTab === 'font' ? 'on' : '' ?>">四、字体制作</a>
<a href="#upgrade" class="<?= $activeTab === 'upgrade' ? 'on' : '' ?>">五、系统升级包</a>
<a href="#reject" class="<?= $activeTab === 'reject' ? 'on' : '' ?>">六、常见拒收原因</a>
</nav>
<main class="tutorial-main">
<section class="tutorial-section" id="rules">
<h2>〇、上传检测总规则</h2>
<p>后台的插件中心、扩展管理、字体设置、主题管理、系统升级都会先自动检测。检测不通过的包会被直接拒绝,不会写入站点;检测通过的包才会安装或升级,并立即投入使用。</p>
<div class="tutorial-check-grid">
<div><strong>结构检测</strong><span>ZIP 是否能正常解压、是否有非法路径、软链接、压缩炸弹。</span></div>
<div><strong>类型检测</strong><span>文件扩展名是否在白名单内,是否夹带 config.php、.htaccess、可执行脚本。</span></div>
<div><strong>语法检测</strong><span>所有 PHP 文件先做语法解析,避免半截代码或损坏文件。</span></div>
<div><strong>兼容检测</strong><span>PHP 版本、站点版本、主题标识、字体文件头是否匹配。</span></div>
<div><strong>危险调用检测</strong><span>插件不允许删除文件、写文件、执行命令、直接改数据库。</span></div>
<div><strong>运行时检测</strong><span>系统升级写入文件后会启动一次新版本引导检查,失败自动回滚。</span></div>
</div>
<p class="tutorial-tip">重要:不要用 ZIP 工具给站点根目录整体打包后直接当升级包。升级包必须带清单、必须去掉 config.php 和 data/uploads/storage。插件包也不要包含站点核心文件。</p>
</section>
<section class="tutorial-section" id="extension">
<h2>一、扩展中心插件制作</h2>
<p>扩展中心上传的包和插件中心使用同一套安装器:支持 ZIP 插件包,也支持单个 JSON 文件。最轻量的做法是制作 JSON,把一段 HTML 挂到首页钩子上。</p>
<h3>1. JSON 扩展包结构</h3>
<pre class="tutorial-code"><code><?= e($extensionJson) ?></code></pre>
<p>字段说明:<code>name</code> 是显示名称;<code>slug</code> 是唯一标识,只能使用英文、数字、短横线;<code>version</code> 不超过 20 个字符;<code>description</code> 不超过 200 字;<code>hook</code> 必须是允许的钩子;<code>html</code> 是前台显示内容,最多 200KB。</p>
<h3>2. ZIP 扩展包结构</h3>
<pre class="tutorial-code"><code>welcome-bar.zip
├── plugin.json
├── plugin.php
└── assets/
└── welcome.css</code></pre>
<p>ZIP 根目录或唯一一层文件夹内必须同时存在 <code>plugin.json</code> 和 <code>plugin.php</code>。可选放置 CSS、JS、图片,但只允许常见的静态资源类型。</p>
<h3>3. 上传与启用</h3>
<p>进入后台「扩展管理」→ 上传自定义扩展包 → 选择 ZIP 或 JSON → 点击上传。检测通过后自动安装并启用,扩展中心会显示入口;也可以在「插件中心」停用或删除。</p>
<p class="tutorial-note">扩展中心是给访客看的入口卡片;插件则是挂在页面钩子上的内容。同一个包会同时出现在两个后台的插件记录里。</p>
</section>
<section class="tutorial-section" id="plugin">
<h2>二、插件中心插件制作</h2>
<p>插件中心适合做“在前台某个位置输出内容”的轻量插件。插件不直接修改站点核心文件,只通过钩子插入页面。</p>
<h3>1. plugin.json 清单</h3>
<pre class="tutorial-code"><code><?= e($pluginJson) ?></code></pre>
<table class="tutorial-table">
<thead><tr><th>字段</th><th>必填</th><th>说明</th></tr></thead>
<tbody>
<tr><td>name</td><td>是</td><td>插件名称,最多 60 字</td></tr>
<tr><td>slug</td><td>是</td><td>英文、数字、下划线、短横线,最多 40 位;同名会被覆盖更新</td></tr>
<tr><td>version</td><td>是</td><td>版本号,例如 1.0.0</td></tr>
<tr><td>description</td><td>否</td><td>简介,最多 200 字</td></tr>
<tr><td>hook</td><td>是</td><td>见下方钩子表</td></tr>
<tr><td>php_min / php_max</td><td>否</td><td>要求 PHP 版本;默认 7.4 起</td></tr>
<tr><td>app_min / app_max</td><td>否</td><td>要求站点版本;不填则不限制</td></tr>
</tbody>
</table>
<h3>2. plugin.php 写法</h3>
<pre class="tutorial-code"><code><?= e($pluginPhp) ?></code></pre>
<p>插件入口必须调用 <code>plugin_register('钩子名', function () { ... });</code>。允许的钩子:</p>
<div class="tutorial-hook-list">
<span><code>home_top</code> 首页顶部</span>
<span><code>home_quote</code> 每日一言下方</span>
<span><code>home_bottom</code> 首页底部</span>
<span><code>home_popup</code> 首页弹窗</span>
<span><code>layout_footer</code> 全站页脚</span>
</div>
<h3>3. 插件包目录</h3>
<pre class="tutorial-code"><code>my-plugin.zip
└── my-plugin/
├── plugin.json
├── plugin.php
└── assets/
├── logo.png
└── plugin.css</code></pre>
<p>为了不破坏站点,插件代码不允许出现删除/写入文件、执行系统命令、引入包外文件、直接操作数据库的调用。插件只负责输出展示内容;需要复杂功能时,请做成系统升级包。</p>
<h3>4. 上传</h3>
<p>后台「插件中心」→ 上传插件包 → 检测通过后自动安装并启用;失败会显示具体原因,文件不会写入正式插件目录。</p>
</section>
<section class="tutorial-section" id="theme">
<h2>三、主题制作</h2>
<p>主题是一个 CSS 文件。制作时先确定唯一的主题标识(例如 <code>tea_blue</code>),CSS 必须全部包在这个选择器里,才能只影响该主题。</p>
<h3>1. 最小可用主题</h3>
<pre class="tutorial-code"><code><?= e($themeCss) ?></code></pre>
<p>标识只能是 2–32 位英文、数字、下划线或短横线;CSS 里必须出现 <code>html[data-theme="你的标识"]</code>,否则上传会被拒绝,因为主题不会生效。</p>
<h3>2. 常用变量</h3>
<p>主题可以覆盖站点的 CSS 变量:<code>--bg</code> 页面底色、<code>--card</code> 卡片底色、<code>--text</code> 主文字、<code>--muted</code> 次要文字、<code>--accent</code> 主色、<code>--accent-2</code> 辅助色、<code>--line</code> 边框色。也可以在主题标识下写具体组件样式,例如 <code>html[data-theme="tea_blue"] .site-header { ... }</code>。</p>
<h3>3. 安全限制</h3>
<p>不允许脚本、<code>@import</code> 外链、<code>expression()</code>、HTML 标签和超出 2MB 的文件;CSS 括号必须成对。建议先在桌面和手机上各看一次,浅色主题不要用纯白字,深色主题不要用深色字。</p>
<h3>4. 上传</h3>
<p>后台「主题管理」→ 填写主题名称与标识 → 拖入 CSS → 上传并加入主题库。检测通过后会出现在前台主题面板;勾选“强制主题”可让访客不能覆盖。</p>
</section>
<section class="tutorial-section" id="font">
<h2>四、字体制作</h2>
<p>字体上传的是单个字体文件,不是 ZIP。支持 <code>woff2</code>、<code>woff</code>、<code>ttf</code>、<code>otf</code>,单个文件不超过 20MB。</p>
<h3>1. 选文件与命名</h3>
<p>优先使用 woff2(体积小、网页加载快);ttf/otf 兼容性好但体积更大。字体名称填中文可读名,例如“黄霄云汉仪体”,不要填文件名乱码。</p>
<h3>2. 版权与完整性</h3>
<p>只上传你有权在网站使用的字体,不要上传来历不明的商用字体。文件必须是真实字体:系统会检查 <code>wOF2</code>、<code>wOFF</code>、<code>OTTO</code>、<code>true</code>、<code>ttcf</code> 或 TrueType 文件头,伪装成字体的图片、脚本、压缩包会被拒绝。</p>
<h3>3. 上传与启用</h3>
<p>后台「字体设置」→ 填名称 → 拖入字体文件 → 上传并加入字体库 → 点“启用”。启用后全站前台和后台统一生效;替换字体时旧文件会被清理。</p>
</section>
<section class="tutorial-section" id="upgrade">
<h2>五、系统升级包制作</h2>
<p>系统升级包是一个完整站点源码 ZIP,用来把整站升级到新版本。它比普通插件更严格:必须带清单、必须版本更高、必须能通过新版本引导检查。</p>
<h3>1. 清单文件</h3>
<p>在升级包根目录放 <code>komorebi-upgrade.json</code>:</p>
<pre class="tutorial-code"><code><?= e($upgradeJson) ?></code></pre>
<table class="tutorial-table">
<thead><tr><th>字段</th><th>说明</th></tr></thead>
<tbody>
<tr><td>type</td><td>固定写 <code>komorebi-upgrade</code></td></tr>
<tr><td>name</td><td>升级包显示名称,最多 80 字</td></tr>
<tr><td>version</td><td>目标版本,必须高于当前版本</td></tr>
<tr><td>app_min / app_max</td><td>允许从哪个站点版本升级;当前版本不在范围内会拒绝</td></tr>
<tr><td>php_min / php_max</td><td>要求 PHP 版本;不填 php_max 表示不限制上限</td></tr>
<tr><td>changelog</td><td>升级说明,会显示在升级记录里</td></tr>
<tr><td>delete</td><td>可选,升级后要删除的旧文件相对路径</td></tr>
</tbody>
</table>
<h3>2. 目录要求</h3>
<pre class="tutorial-code"><code>komorebi-upgrade.zip
├── komorebi-upgrade.json
├── index.php
├── inc/
├── pages/
├── admin/
├── assets/
├── README.md
└── sw.js</code></pre>
<p>必须包含:<code>index.php</code>、<code>inc/bootstrap.php</code>、<code>inc/helpers.php</code>、<code>inc/db.php</code>、<code>pages/admin.php</code>、<code>assets/css/app.css</code>。只允许这些顶层目录:<code>assets</code>、<code>inc</code>、<code>pages</code>、<code>admin</code>、<code>plugins</code>;以及 <code>index.php</code>、<code>api.php</code>、<code>manifest.php</code>、<code>robots.txt</code>、<code>rss.php</code>、<code>sitemap.php</code>、<code>sw.js</code>、<code>README.md</code>。</p>
<p class="tutorial-danger">绝对不要打包:<code>config.php</code>、<code>data/</code>、<code>uploads/</code>、<code>storage/</code>、<code>install.php</code>、<code>.htaccess</code>、<code>.user.ini</code>、<code>.git/</code>。包含这些的包会被直接拒绝。</p>
<h3>3. 版本一致性</h3>
<p>源码里的 <code>inc/bootstrap.php</code> 必须把自己的 <code>APP_VERSION</code> 改成与清单 <code>version</code> 完全一致,例如都写 <code>6.25.33</code>。清单说 6.25.32 但源码还是 6.24.0,会被判为不一致而拒绝。</p>
<h3>4. 制作流程</h3>
<ol class="tutorial-steps">
<li>复制当前站点完整源码到工作目录,不要复制 config.php、data、uploads、storage。</li>
<li>完成代码修改,跑一遍所有 PHP 文件的语法检查;建议先在测试站完整点一遍首页、帖子、个人主页、后台。</li>
<li>修改 <code>inc/bootstrap.php</code> 的 APP_VERSION、<code>sw.js</code> 缓存版本、README 版本说明。</li>
<li>在根目录写 <code>komorebi-upgrade.json</code>,把 app_min 设为当前线上版本,app_max 设为当前小版本范围。</li>
<li>把源码和清单打成 ZIP,确认解压后第一层就能看到清单与 index.php;不要多套一层无意义的文件夹。</li>
<li>到后台「系统升级」拖入 ZIP。系统会先检测,再自动备份旧版核心文件、应用新文件并做一次运行时引导检查。</li>
</ol>
<h3>5. 升级后的行为</h3>
<p>检测通过后自动投入使用,并在 <code>storage/upgrades/</code> 保留核心文件备份。升级记录可以点“回滚文件”恢复升级前源码;如果新版本改了数据库结构,回滚源码后还需要去「备份恢复」恢复对应时间点的数据库备份。</p>
<p class="tutorial-note">升级过程会短暂打开维护模式,完成后自动恢复原来的维护设置。升级包不要依赖某个具体主机路径,也不要在包里写死域名。</p>
</section>
<section class="tutorial-section" id="reject">
<h2>六、常见拒收原因</h2>
<div class="tutorial-reject-list">
<p><strong>ZIP 路径穿越</strong><span>包含 <code>../</code>、绝对路径或软链接,直接拒绝。</span></p>
<p><strong>夹带配置与数据</strong><span>升级包包含 config.php、data、uploads、storage、install.php,直接拒绝。</span></p>
<p><strong>版本不兼容</strong><span>PHP 版本不满足、站点版本不在 app_min/app_max 范围、升级包版本不高于当前版本。</span></p>
<p><strong>源码版本不一致</strong><span>清单 version 与 inc/bootstrap.php 的 APP_VERSION 不一样。</span></p>
<p><strong>语法错误</strong><span>任意 PHP 文件解析失败,整包拒绝,不会安装一半。</span></p>
<p><strong>插件越权</strong><span>插件代码出现删除、写入、执行命令、直接改数据库、引入包外文件,整包拒绝。</span></p>
<p><strong>主题不生效</strong><span>CSS 缺少 <code>html[data-theme="标识"]</code>,或包含脚本/外链导入。</span></p>
<p><strong>字体伪装</strong><span>文件头不是真实字体,或扩展名不在 woff2/woff/ttf/otf 内。</span></p>
</div>
<p class="tutorial-tip">上传失败时先看红色提示的具体原因;修正后重新打包再传。系统不会把“没通过检测”的包偷偷放进站点。</p>
</section>
</main>
</div>
<?php render_footer(); ?>