KX-Park 主题手册

Typecho 个人生活博客主题 · 完整功能介绍与使用说明
适用版本：1.17.9 ｜ 配套插件：MofangKit 1.3.0 ｜ 开发环境：Typecho 1.3.0 / PHP 8.3 / MySQL
最后更新：2026-10-05

1. 这是什么

KX-Park 是一个为「个人生活博客」而生的 Typecho 主题。

它的定位不是通用 CMS 模板，而是一个人的数字公园——名字取自「开心公园」（KX = 开心），与同门的 KX-Verse 属同一命名家族。它假设你的博客主要记录这些东西：随手写的短句、拍的照片、在听的歌、去过的地方、读过的书，以及那些不值得写成完整文章、但丢掉又可惜的碎片。

所以它把「记录」拆成了不同颗粒度的容器：

它同时也很适合技术博客：代码高亮、自动目录、阅读时长、相关文章、GitHub 仓库卡、下载文件卡一应俱全。

2. 设计理念

夜色优先，双色令牌

主题的配色建立在一套 HSL 双色令牌上，而不是写死的十六进制值：

--main-color: 215deg 75% 55%;   /* 主题主色：只定色相，明度饱和度由主题推导 */
--font / --back / --line ...     /* 字色 / 底色 / 边框，全部由色相派生 */

你只需要在设置里填一个色相角（比如 215deg 是蓝、20deg 是橙红、150deg 是青绿），整站的强调色、卡片描边、按钮、进度条、标签、链接下划线会全部跟着变，亮色和深色两套主题各自推导出合适明度，不需要你做两套配色。

三态外观

浅色 / 深色 / 跟随系统三种模式随时切换，选择记在浏览器本地。页面 <head> 里有一段极小的内联脚本，在 CSS 加载之前就把模式定好，所以切换页面不会闪白。

零外部依赖

这是本主题比较硬的一条自我要求：

• 图标：内置 assets/icons.svg 本地雪碧图，69 枚 Tabler 风格线条图标，随页面一次性内联注入，不发任何图标请求
• 表情：63 个阿鲁 + 71 个泡泡表情包全部本地化，WebP 格式
• 代码高亮：highlight.js 本地资源，亮暗两套配色
• 二维码：本地 qrcode.min.js
• 字体：海报用的中文字体随插件打包

也就是说，把一个访客从国外 CDN 上救回来这件事，本主题不参与——它不需要。

一致的交互语言

• 卡片体系：16px 圆角、极轻阴影、悬浮时只过渡合成属性（不重绘）
• 动效有统一令牌（--ease-out / --t-base 等），可在设置里整档切换「丰富 / 轻量」
• PJAX 无刷新导航，切页时音乐播放器不中断

3. 功能总览

首页

• 全屏星空封面：可换成自己的大图，含斜体大标语、一句话签名、站点统计（文章数 / 评论数 / 建站天数）、社交按钮、随机一篇文章按钮
• 置顶区：编辑文章时勾选「置顶」即出现在首页最顶部
• 瞬间流：读取指定分类下的短内容，微博式卡片
• 焦点大卡区：整站文章流，首篇占双宽
• 精选分类：分类色卡组，自动轮换四种色相
• 图文动态墙：自动从最近文章里提取图片，组成图片墙
• 以上五个模块顺序可自定义，可逐个开关

文章页

• 封面图（字段指定，或自动取正文第一张图）
• 图标化元信息：日期 / 作者 / 分类 / 字数 / 阅读时长 / 阅读热度
• 心情标记（自定义字段 mood）
• 阅读进度条（顶部随滚动前进）
• 自动目录（提取 h2/h3，可折叠）
• 代码块一键复制 + 语言标签
• 上下篇导航、标签、相关文章（同分类按热度，不足补最新）
• 文末版权声明（可开关自定义文案）
• 音频 / 视频区块（自定义字段）
• 音乐卡片（封面模糊底 + 进度拖拽 + LRC 歌词滚动高亮）
• 互动条：点赞 / 打赏 / 分享（含生成海报）

页面模板

评论区

• 中文相对时间（「昨天 17:08」）
• IP 打码显示（124.116.244.*）
• 楼层号 #1
• 博主徽章
• 嵌套回复，就地展开，自动带「回复 @某人：」前缀
• 表情面板（阿鲁 / 泡泡 / 颜文字三组）
• 评论头像本地化缓存，五种头像源可选

全站

• PJAX 无刷新导航 + 链接悬停预取 + 前进后退还原滚动位置
• 音乐播放器（悬浮唱碟，PJAX 切页不断播）
• 弹出式灯箱（旋转 / 镜像 / 缩放 / 多图切换）
• 公告气泡（8 秒自动消失，访客关闭后本地记忆）
• 页脚一言（本地池随机，或 Hitokoto API 实时拉取）
• 本站已运行秒级实时计时
• 返回顶部、内容渐入、图片渐显、大图自动缩略图

后台

• 设置页顶部信息卡（主题版本 / Typecho 版本 / 缓存状态）
• 八个页签分栏：首页与封面 / 导航菜单 / 内容流 / 文章页 / 评论与互动 / 公告与互动 / 侧栏 / 性能与外观
• 工具栏一键：备份设置 / 还原备份 / 删除备份 / 清除缓存
• 顺序类设置（首页模块、侧栏模块、导航菜单）支持拖拽排序

4. 安装与启用

环境要求

• Typecho 1.2+（开发环境 1.3.0）
• PHP 7.4+（开发环境 8.3）
• 需要 json / mbstring 扩展；大图缩略图功能需要 GD 或 Imagick 之一（都没有时自动回退原图，不影响使用）

安装步骤

1. 把 mofang 目录整体放进 Typecho 的 /usr/themes/ 下
   （目录名保持 mofang 不要改，Typecho 以目录名作为主题的唯一标识）
2. 把 MofangKit 目录放进 /usr/plugins/ 下
3. 后台 → 控制台 → 外观，找到 KX-Park，点「启用」
4. 后台 → 控制台 → 插件，启用 MofangKit
5. 进入 设置外观，按下一节的向导配置

关于伴侣插件 MofangKit

它不是必需品，但强烈建议启用。启用后你能得到四块能力：

停用插件不会让站点坏掉：编辑器恢复系统默认；友链自动回退到主题设置里的文本（linkItems）；已发布文章里的短代码标签依然由主题正常渲染。

5. 五步上手

空站启用主题后，跟着这五步走一遍，站点就成型了。

第一步：创建「瞬间」分类

瞬间流读取的是一个指定分类下的文章。

1. 后台 → 管理 → 分类，新建一个分类，比如「瞬间」
2. 记下它的缩写名（slug），假设是 moments
3. 回到主题设置 → 内容流 → 瞬间分类缩写名，填 moments

以后凡是写一两句话的短内容，就发到这个分类下，它会自动出现在首页「瞬间」模块里。

第二步：创建四个功能页面

后台 → 管理 → 独立页面，新建四个页面，每个都在右侧「自定义模板」下拉里选对应的模板：

注意：模板文件必须存在且 contents.template 字段带 .php 后缀。通过后台下拉选择会自动写对；如果你是手工改数据库，一定要写成 page-timeline.php 这种带后缀的形式，否则主题会静默回退到普通页面模板。

第三步：配顶部导航

主题设置 → 导航菜单 → 导航菜单，每行一条，格式：

名称|地址[|新窗口]

地址可以写这几种：

第三列填 1 / blank / 外链 / 新窗口 中任意一个，就是在新标签页打开。

完整示例：

首页|/
瞬间|page:moments-page
时光轴|page:timeline
图库|page:gallery
友情链接|page:links
GitHub|https://github.com/yourname|1

留空则自动列出全部独立页面（旧行为）。设置页里可以用拖拽调整顺序，也可以直接改文本。

第四步：填内容

主题设置 → 首页与封面：

• 封面大标语：封面上的英文大字，会以粗斜体显示，比如 A LIFE BLOGGER
• 一句话签名：大标语下方的中文小字
• 封面背景图：首页全屏封面用的图，留空则用内置 CSS 星空
• 头像地址：侧栏概览卡与瞬间作者头像
• 建站日期：用于封面统计与周年卡
• 社交按钮：每行 名称|链接

主题设置 → 内容流：

• 图库：每行 图片URL|标题
• 播放列表：每行 名称|音频链接|封面图URL(可选)
• 精选分类缩写名：多个用英文逗号分隔，留空则自动取文章最多的前三个

第五步：接入 GIF 之外的细节

• Logo：设置 → 性能与外观 → 填 Logo（昼间）与 Logo（夜间）两张图的 URL，深色模式自动切换；只填一张则共用；都不填就显示站点名称文字
• 主题色相：同页的「主题色相」填一个角度值，比如 215deg 蓝、20deg 橙红、150deg 青绿
• 页脚：备案号、页脚文案、一言来源

完成后清一下缓存（设置页工具栏「清除缓存」），前台刷新即可。

6. 主题设置逐项说明

后台 → 控制台 → 外观 → 设置外观。设置页按八个页签分栏，下面按页签列出全部选项。

保存方式：改动后点右下角悬浮的「保存设置」按钮，或工具栏里的保存。有未保存改动时会有提示。

6.1 首页与封面

PJAX 与「跟随系统」的取舍：如果站点装了 VisitorLoggerPro 之类的统计插件，PJAX 会导致页面浏览量统计不到（因为没发生真实页面跳转）。这种情况把 PJAX 关掉，或改用支持 PJAX 的统计方案。

6.2 导航菜单

6.3 内容流

6.4 文章页

6.5 评论与互动

表情码写法（在评论框里直接输入就会显示对应的图）：

点击表情面板里的表情会自动插入对应文本码，不需要你手记。

6.6 公告与互动

6.7 侧栏

安全提醒：「广告位内容」是原样输出的 HTML，只有管理员能填，所以是安全的。但不要把它做成访客可提交的内容。

6.8 性能与外观

7. 写作：编辑器与短代码组件

7.1 Editor.md 编辑器

启用 MofangKit 后，撰写文章 / 独立页面的系统编辑器会被替换为 Editor.md：

• 左侧写 Markdown，右侧实时预览（可关闭）
• 内置 CodeMirror，代码编辑体验接近桌面编辑器
• 工具栏含加粗 / 斜体 / 标题 / 列表 / 链接 / 图片 / 表格 / 代码块 / 全屏等
• 全部资源本地化，不发任何外部请求
• 发布时自动把 Markdown 同步回原文 textarea，兼容草稿与自动保存
• 编辑器高度可在插件设置里调整（默认 560px）

停用插件即恢复系统编辑器。

7.2 短代码工具栏

在 Editor.md 原生工具栏的右侧，插件追加了 29 个组件按钮 + 1 个帮助按钮。点按钮 → 弹窗填参数 → 确定 → 标签插入到光标处（有选中文字时会作为内容包进去）。

所有组件都只是写进正文的方括号标签，渲染 100% 在服务端完成，前端零依赖（只有「复制按钮」和「文章目录」需要一点点 JS，已随主题本地加载）。所以：

• 你可以直接手写这些标签，不装插件也照样生效
• 停用插件后，已发布文章里的标签依然正常渲染
• 标签页用 radio + label 纯 CSS 实现，不需要 JS，PJAX 换页后依然可用

写作建议：短代码标签和普通 Markdown 可以随意混排。空行分隔更稳妥，块级标签独占一行。

7.3 组件速查与示例

① 版式

[center]我是居中的一段话[/center]

[right]—— 鲁迅[/right]

② 提示条

四种语义色，可自定义标题。[tip] 是通用写法，用 type 指定颜色。

[success]操作成功了。[/success]

[info title="你知道吗"]这是 info 提示条，支持自定义标题。[/info]

[warning]这一步会覆盖原文件。[/warning]

[danger]删库跑路之前请三思。[/danger]

[tip type="success" title="保存成功"]用 tip 也可以，效果一样。[/tip]

③ 标签卡

纯 CSS 切换，无 JS。可以放任意多页，每页标题自定义。

[tabs]
[tab name="Windows"]
在这里写 Windows 下的做法。
[/tab]
[tab name="macOS"]
在这里写 macOS 下的做法。
[/tab]
[tab name="Linux"]
在这里写 Linux 下的做法。
[/tab]
[/tabs]

④ 折叠框

适合放长附录、大段配置、剧透。

[collapse title="点我展开完整配置"]这里是折叠面板里的内容，适合放长文附录。[/collapse]

[collapse title="默认就展开" open]加上 open 就默认展开。[/collapse]

⑤ 相册（单图）

给一张图配上说明，以卡片形式展示。

[photo title="延安的傍晚"]
![延安](https://pic.qu.pw/img/20260623/8c1b5076c2b77d01f90e956ded6f5546.jpg)
[/photo]

⑥ 图片网格

四个断点分别设定每行几张图，可选统一宽高比。

[grid set="2,3,4,4"]
![图1](https://example.com/1.jpg)
![图2](https://example.com/2.jpg)
![图3](https://example.com/3.jpg)
![图4](https://example.com/4.jpg)
[/grid]

[grid set="2,3,4,4" bili="16x9"]
![宽图](https://example.com/wide.jpg)
[/grid]

set 的四个数字依次是：手机 / 平板 / 大平板 / 桌面 每行张数（各 1~8）。

bili 可选宽高比：21x9 16x9 4x3 2x3 10x14 3x4 1x2 2x1 3x1 4x1 1x1。

⑦ 时间线

每行一条，日期可选。日期支持 2021-06、2021.6.1、6月1日 等写法，后面接内容。

[timeline]
2021-06 毕业
2022-01 开始工作
2023-09 搬到了南京
2024-03 开始写博客
没有日期的行也可以，就显示成一条普通节点
[/timeline]

⑧ 友链卡片

三种写法都行。

<!-- 单张，属性写法 -->
[link name="Typecho 官网" desc="轻量高效的博客程序" url="https://typecho.org" logo="https://typecho.org/favicon.ico"]

<!-- 单张，配对写法 -->
[link]Typecho 官网|轻量高效的博客程序|https://typecho.org|https://typecho.org/favicon.ico[/link]

<!-- 多张 -->
[links]
Typecho 官网|轻量高效的博客程序|https://typecho.org|https://typecho.org/favicon.ico
某位朋友|他的博客|https://friend.example.com|
[/links]

多张的每行格式是 名称|描述|链接|Logo，Logo 可以留空，留空时自动显示名称首字作为头像。

⑨ 下载文件 / PDF

[file href="https://example.com/tool.zip" name="工具包 v2.1（12MB）"]

[pdf url="https://example.com/paper.pdf" name="论文全文"]

⑩ 地点卡片

生成一张地点卡片，带高德 / 百度 / 腾讯三个地图的跳转按钮（不嵌入地图，避免额外请求与隐私问题）。

两种写法：写经纬度属性，或直接写坐标。

[map name="延安" lng="109.4897" lat="36.5853" zoom="15"]

[map name="我家" 109.4897,36.5853]

zoom 可选，范围 3 ~ 19，默认 15。

⑪ GitHub 仓库卡

[github repo="typecho/typecho"]

⑫ 引用文章

按文章 ID 生成一张引用卡（带标题与摘要）。文章 ID 可以在后台文章列表的链接里看到。

[post cid="3"]

⑬ 文章目录

把目录插入到正文的任意位置（不依赖主题的整体目录开关）。

[postindex]

主题会自动收集正文里所有 h2/h3 标题生成锚点，点在目录上直接跳转。

提示：即使你关掉了「本文目录」，只要正文里写了 [postindex]，锚点依然会生成，目录也能用。

⑭ 音频

[audio url="https://example.com/song.mp3"]

也可以配对写，把链接放在标签中间：

[audio]https://example.com/song.mp3[/audio]

[music] 是 [audio] 的别名，效果一样。

⑮ 音乐卡片

带封面、进度条、可展开的滚动歌词。

[musiccard url="https://example.com/song.mp3" name="父亲写的散文诗" artist="许飞" cover="https://example.com/cover.jpg"]
[00:00.00]一九八四年 庄稼还没收割完
[00:06.50]女儿躺在我怀里 睡得那么甜
[/musiccard]

歌词用标准 LRC 格式（[分:秒.毫秒]歌词）。歌词留空时卡片不出现「歌词」按钮。卡片背景会用封面图做模糊底。

⑯ 视频

支持 mp4 直链、B 站、腾讯视频、YouTube。

<!-- 直链，可加封面 -->
[video src="https://example.com/movie.mp4" pic="https://example.com/poster.jpg"]

<!-- B 站（写完整链接或 BV 号都行） -->
[video src="https://www.bilibili.com/video/BV1xx411c7mD"]

⑰ 哔哩哔哩

专门给 B 站的简写。

[bilibili bv="BV1xx411c7mD"]

⑱ 文本样式

给一段文字上色或加装饰。可叠加。

[text color="red"]红色的字[/text]

[text color="blue" depth="700"]更深的蓝[/text]

[text deco="wavy"]波浪线[/text]

[text color="green" deco="double"]绿的双下划线[/text]

⑲ 文本复制按钮

[copy text="npm install kx-park"]复制安装命令[/copy]

点击按钮把 text 的内容复制到剪贴板。text 里的双引号需要转义成 \"。

⑳ 按钮链接

[btn href="https://bk.qu.pw" type="blue"]访问我的博客[/btn]

㉑ 渐变虚线分隔

一条两端渐变的虚线，用来分隔正文段落。

[dotted startColor="#ff6c6c" endColor="#73aaff"/]

㉒ 登录可见

内容只对已登录用户显示。

[login]
这段内容需要登录后才能看到。
[/login]

未登录访客会看到「登录后可见，请先登录」的提示，带登录链接。

㉓ 评论可见

内容只对该文章下已发表过评论的读者显示。

[hide]
嘿嘿，先留个言才能看到哦。
[/hide]

判定方式是按评论者记忆 cookie（昵称 + 邮箱）比对本站已通过的评论。

㉔ 行内标记

[mark]高亮标记[/mark]

[center]居中文本[/center]

7.4 关于 Markdown 渲染的一处细节

Typecho 的 Markdown 解析器（HyperDown）会把块级标签包进 <p> 里、并在软换行处插 <br>。主题在渲染前有一趟归一化预处理，会自动剥掉这些多余的包裹，所以你不需要担心标签前后要不要空行。但为了可读性，块级标签独占一行、前后留空行仍是推荐的写法。

代码块里的方括号不会被当短代码执行。 主题渲染短代码前会先把 <pre>…</pre>（代码块）与 <code>…</code>（行内代码）整段保护起来，处理完再原样放回。所以写教程、贴示例时，把 [tip]…[/tip] 这类写法放进反引号或代码围栏里就会原样显示，不会真的渲染成组件——本文档里的所有示例就是这么写的。

8. 文章自定义字段

在文章 / 独立页面的编辑页下方，主题注入了这些字段。它们作用于整篇文章，和正文里的短代码是互补关系。

字段 vs 短代码，怎么选

两者可以共存，不会冲突。

9. 页面模板使用

新建独立页面时，在右侧「自定义模板」下拉里选择。四个模板各有专属 hero 头图。

瞬间

短内容瀑布流，读取你在设置里指定的「瞬间分类」，条数由「瞬间显示条数」控制。适合微博式的日常记录。

归档时光轴

把全部文章按年份分组，一年一段，形成一条时间线。适合展示博客的成长轨迹。

友情链接

一页包含三块：

1. 友链卡片：精致卡片，含站点 Logo（自动取对方站 /favicon.ico，失败时回退首字）、名称、简介
2. 订阅动态：抓取各友链的 RSS，按时间合并展示各友站最新文章
3. 自助申请表单：访客填写站点名称 / 链接 / Logo / 联系邮箱 / 简介 / RSS 提交，详见下一节

图库

图片网格，内容来自主题设置的「图库」选项，每行 图片URL|标题。留空时显示「图库还是空的」提示。

10. 友链申请与审核系统

由 MofangKit 插件提供。默认状态：

申请者视角——在友链页填表提交，页面会即时反馈结果，不需要刷新。

站长视角——收信 + 后台审核。

10.1 前台申请

友链页底部的申请表单。提交后会立刻给出结果提示（AJAX），没有 JS 时自动降级为普通表单提交并跳回。

表单字段：站点名称 / 站点链接 / Logo / 联系邮箱 / 站点简介 / RSS 订阅地址（选填）。

10.2 站长收信

有新申请时，主题会给站长发一封提醒邮件，邮件里带一个一键审核按钮，点进去直接到后台面板。

收件人的解析顺序：

1. 插件设置里的「新申请通知邮箱」
2. CommentNotifier 插件的站长邮箱
3. 站点第一个管理员的邮箱

前提：需要配置好 CommentNotifier 插件（SMTP）。如果都没配置，插件会在设置页用红字告警，但审核动作本身不受影响，只是不发信。

10.3 后台审核面板

后台 → 管理 → 友情链接。

面板包含：

• 状态页签：待审核 / 已通过 / 已拒绝 / 全部，各带计数
• 行内操作：通过 / 拒绝 / 编辑 / 删除
• 右侧表单：手动新增或修改友链
• 拖拽排序：直接拖表格行调整前台展示顺序

点「通过」或「拒绝」时，系统会自动给申请人回一封信（可在插件设置里关掉）。

10.4 插件设置项

关于「提交频率限制」：它依赖 X-Forwarded-For 头来得到客户端 IP。如果本站前面挂了 CDN 或反向代理，这个头是可以被访客伪造的，限流就形同虚设。这种情况下关掉这个开关，别留虚假的安全感——同源校验与蜜罐（隐藏字段）仍在生效。

10.5 申请防护

• 只接受 POST 请求
• 同源校验（Origin / Referer 主机必须与本站一致）
• 蜜罐字段（正常访客看不到、机器人会填的隐藏输入框）
• 重复站点去重；被拒绝的站点允许重新提交并回到待审状态
• 链接强制 http(s) 协议

11. 分享海报

文章 / 页面底部互动条的「生成海报」按钮，点击后弹出一张 750×1000 的分享卡片，可直接下载 JPEG。

海报内容

主题色渐变底 + 点阵纹理、白圆角卡、文章封面（圆角裁切）、站点头像（圆形）、标题、摘要、二维码、页脚。

技术要点

• 服务端渲染：由 MofangKit 在服务端出图，使用随插件打包的中文字体（Noto Sans CJK SC 子集），中文不会掉成方块或宋体
• 排版自适应：二维码位置由卡片底边反推，摘要行数再由二维码上方的剩余高度反推——标题再长也不会溢出卡片
• 缓存：渲染结果缓存在插件目录的 .cache/ 下，记录内容版本戳；标题 / 摘要 / 封面 / 站点配置变化或超过 30 天自动重出。首次约 0.1~0.3 秒，命中约 0.03 秒
• 限额：公开端点，同一 IP 每 10 分钟最多触发 20 次实际渲染。命中缓存的请求不计数，所以正常浏览完全不受影响

关闭它

设置 → 公告与互动 → 「生成分享海报」选「隐藏」，或直接停用 MofangKit 插件（此时前端会提示「海报生成失败，请稍后重试」并提供重试按钮）。

12. 性能、缓存与 SEO

12.1 缓存机制

主题自带一层轻量文件缓存，用于统计 / 热门文章 / 图文墙 / 随机池 / 友链订阅等聚合查询。

• 缓存目录：主题目录下的 cache/
• 有效期：由「缓存时间（秒）」控制，默认 600 秒
• 自动失效：站点内容变化（发文 / 评论 / 改设置）会改变「修订戳」，缓存即刻失效，不需要你手动清
• 自动降级：缓存目录不可写时，全部查询自动改为实时执行，不会报错

设置页工具栏有「清除缓存」按钮，以及在性能与外观里的版本信息卡上能看到当前缓存项数。

12.2 图片优化

• 大图自动缩略图（默认开）：Logo、封面、站点图标这类远端大图，会按实际显示宽度缩成 WebP 再输出。效果显著——一张 4MB 的 Logo 可以降到约 20KB。缓存 30 天
• 图片渐显（默认开）：懒加载图片解码完成后淡入，避免「半张图刷出来」的突兀感
• 首屏优化：封面图 preload + fetchpriority=high，并对图片托管域名做 preconnect

12.3 页面性能

• PJAX：站内跳转不重新加载整页，音乐播放器不中断
• 链接悬停预取：鼠标悬停时提前拉目标页，点击后近乎瞬时
• 滚动性能：滚动回调用 requestAnimationFrame 合并，scrollHeight 缓存起来不在每帧重算
• 离屏跳过：长列表里靠后的卡片启用 content-visibility: auto，减少首屏渲染负担
• 毛玻璃降级：不支持 backdrop-filter 的浏览器、或系统开了「减少透明度」时，自动降级为不透明底色

12.4 SEO

主题内置输出：

• <title> 按页面类型自动拼装（分类 / 搜索 / 标签 / 作者 / 日期）
• 文章的 rel="canonical"
• Open Graph 标签（og:type / og:url / og:title / og:description / og:site_name）
• Twitter Card
• RSS / Atom 的 rel="alternate"
• /sitemap.xml：由 MofangKit 提供，覆盖首页 / 文章 / 独立页面 / 分类 / 标签。URL 全部按你的伪静态规则反解析生成，改伪静态不用改代码。只收录已发布、未加密、已到发布时间的内容
• /robots.txt：站点根的静态文件，声明 Sitemap 地址并挡掉 /admin/、/action/

提醒：robots.txt 里 Sitemap: 那一行写的是绝对地址。如果以后换域名，记得把这一行一起改掉，否则搜索引擎会在旧域名上找站点地图。

12.5 关于「浏览量」是怎么统计的

文章页被访问时，主题会在 themeInit 阶段给该文章的 views 字段 +1，存在 typecho_fields 表里。没有用任何第三方统计插件，所以这个数字是"主题级别"的粗略计数：

• 刷新页面会重复计数（没有做 IP 去重）
• 爬虫访问也会计数
• PJAX 站内跳转不会触发（因为没有真正加载新页面）——所以站内流转不会虚增数字

如果你需要更精确的统计，装一个专业统计插件，并把热度的展示关掉（设置 → 文章页 → 「阅读热度」隐藏）。

12.6 可访问性

• 图标 SVG 统一带 aria-hidden="true"，避免读屏器念出一串无意义内容
• 交互元素带 aria-label
• :focus-visible 焦点样式
• 尊重 prefers-reduced-motion：系统开了「减少动态效果」时自动关闭渐入与位移
• 打印样式：自动隐藏导航 / 侧栏 / 评论区，只保留正文

13. 目录结构

usr/themes/mofang/                 ← 主题目录（目录名请勿修改）
├── index.php                      首页
├── header.php                     全站头部（含 SEO、图标注入、导航）
├── footer.php                     全站页脚（含一言、运行计时、播放器）
├── post.php                       文章页
├── page.php                       独立页面
├── archive.php                    分类 / 标签 / 搜索 / 日期归档页
├── comments.php                   评论区与评论表单
├── 404.php                        404 页
├── functions.php                  主题核心（约 2900 行：设置、短代码渲染、各类 helper）
├── page-moments.php               页面模板：瞬间
├── page-timeline.php              页面模板：归档时光轴
├── page-links.php                 页面模板：友情链接
├── page-gallery.php               页面模板：图库
├── README.md                      开发者文档（版本变更记录）
├── MANUAL.md                      本文件
├── screenshot.png                 主题预览图（后台「外观」列表显示）
├── demo-tone.wav                  演示音频
├── favicon.ico                    默认站点图标
├── assets/
│   ├── style.css                  全站样式（双色令牌 + 六档断点）
│   ├── main.js                    全站脚本（PJAX、播放器、灯箱、互动绑定）
│   ├── icons.svg                  69 枚本地图标雪碧图
│   ├── qrcode.min.js              本地二维码库
│   ├── thumb.php                  大图缩略图端点
│   ├── hljs/                      highlight.js（含亮暗两套配色）
│   ├── owo/                       评论表情包（aru 63 + paopao 71）
│   └── foreverblog/               十年之约 / 穿梭虫洞徽章
└── cache/                         运行时缓存（可写即可，删掉会自动重建）
    ├── avatars/                   本地化评论头像
    ├── likes/                     点赞去重标记
    └── thumbs/                    缩略图产物与登记索引

usr/plugins/MofangKit/             ← 伴侣插件
├── Plugin.php                     插件主类（激活注册钩子与路由）
├── Action.php                     点赞端点 /action/mofang
├── LinkModel.php                  友链数据模型
├── LinkAction.php                 友链前台申请端点
├── LinkAdmin.php                  友链后台审核端点
├── Mailer.php                     发信
├── manage-links.php               后台审核面板
├── Poster.php                     服务端海报渲染
├── PosterAction.php               海报端点
├── SitemapAction.php              站点地图 /sitemap.xml
├── assets/                        Editor.md 全套本地资源 + 短代码工具栏
├── lib/                           phpQrcode + 中文字体
├── .cache/                        海报与站点地图缓存（Web 不可访问）
└── logs/                          发信日志（Web 不可访问）

14. 常见问题

Q：换了主题名，但后台还显示 mofang？

后台「外观」列表显示的名字来自主题 index.php 顶部的 @package 注释。目录名可以保持 mofang 不变——Typecho 用目录名作主题的唯一标识，改目录需要同步数据库里的 theme 值和插件里的硬编码路径，不建议动。

Q：首页某个模块不见了？

按顺序检查三处：① 该模块的显示开关是否被关掉；②「首页模块顺序」里是否漏写了它的 key（漏写不会丢，会自动补到末尾，所以更可能是开关）；③ 该模块是否有内容（比如「图文动态」需要文章正文里有图片，「瞬间」需要指定的分类下有文章）。

Q：瞬间流是空的？

「瞬间分类缩写名」必须填真实存在的分类 slug，且该分类下要有文章。默认值 moments 只是占位。

Q：页面用了模板，但显示的还是普通页面？

模板文件第一段 docblock 必须紧跟 <?php 且含 @package custom；同时数据库里 contents.template 字段的值必须带 .php 后缀（如 page-timeline.php）。后台下拉选择会自动写对。

Q：评论提交后没反应 / 提示验证失败？

Typecho 的反垃圾令牌在 PJAX 下有个经典坑：官方做法是把令牌存在 sessionStorage 里、首次鼠标移动时填进表单，但 PJAX 只换页面内容、不重跑 <head> 脚本，翻页后令牌就一直是空的。本主题的表单直接把令牌服务端渲染进表单，所以 PJAX 下也能正常提交。如果你遇到了这个问题，先确认是不是改过 comments.php。

Q：翻页之后点赞 / 播放 / 分享按钮失灵？

这类问题的通病是：事件绑定写在了顶层，而 PJAX 换页只替换容器内容、不会重跑顶层脚本。本主题已把所有会随 PJAX 出现的元素（互动条、音乐卡片等）的绑定统一放进每次换页都会执行的初始化函数里。如果你自己扩展了功能，请遵循同一条纪律：随 PJAX 出现的 DOM，绑定必须写在 initPage() 里。

Q：音乐播放器封面糊了 / 被拉成横条？

播放器封面是方形设计（4.6rem 小方图），请把封面源图准备成方形，且分辨率不要低于 300×300。原图太小会被放大导致模糊。

Q：海报里中文是方块 / 乱码？

说明随插件打包的中文字体没被读到。检查 usr/plugins/MofangKit/lib/fonts/ 下是否有 NotoSansSC-Regular.otf 和 NotoSansSC-Bold.otf 两个文件（每个约 3MB）。这是刻意的设计——本站的 PHP 池开了 open_basedir，读不到系统字体目录，所以字体必须随插件走。

Q：点赞数怎么不涨 / 数字跳动？

点赞有防重复：同一 IP、同一内容 3 秒内只计一次，且访客浏览器本地会记住已赞状态，再次点击不会发请求。这是正常行为。

另外，浏览量 / 点赞数的权威值存在 typecho_fields 表的 str_value 列。如果你手工改过数据库，请两列（str_value 与 int_value）一起改，保持同步。

Q：/sitemap.xml 或 /robots.txt 打开是 404？

sitemap.xml 需要 MofangKit 处于启用状态（它是插件注册的路由）。robots.txt 是站点根目录的静态文件，与插件无关——如果被删掉了，重新建一个，内容里记得把 Sitemap: 那行的域名改成你的。

Q：站点地图多久更新一次？

内容有变化就立刻更新。它靠一个「修订戳」判断：统计文章表的最后修改时间 / 最大 ID / 总条数，以及分类表的归类变化。任一变化即重新生成；没变化就复用缓存文件，爬虫高频抓取也不会有额外开销。

Q：缓存目录可以删吗？

可以。删掉后首次访问会自动重建。只要保证 cache/ 目录对 PHP 进程可写即可（通常是 www:www 755）。不可写时主题会自动降级为实时查询，不会报错。

Q：想让整站更"素"一点？

设置 → 性能与外观 → 「动效强度」选轻量。会关掉滚动渐入、错落延迟、悬停位移，只保留必要的状态过渡。也可以配合系统级的「减少动态效果」使用，效果一致。

Q：怎么改成单栏？

设置 → 侧栏 → 「侧栏总开关」选隐藏。首页会变成单栏布局，分页仍然保留。

Q：后台「外观」列表里的主题预览图是默认占位图？

Typecho 会自动抓取主题根目录下名为 screenshot 的图片（支持 png / jpg / jpeg / gif / bmp / webp / avif）作为预览，抓不到才回退默认占位图 noscreen.png。主题已随包附带 screenshot.png（1912×948 首页整屏）；若被删掉，把它放回主题根目录即可，无需改任何设置。后台按 max-width:100%; max-height:240px 缩放显示，所以横版宽图最合适。

附录：版本与命名

版本号规则：A.B.C —— 小改动进位 C，中等改动进位 B，大改动进位 A；满 10 进位；遇 4 跳过。

本手册随主题一起维护。发现文档与实现不一致时，以代码为准，并请把差异反馈回来。