KX-Park 主题手册

Typecho 个人生活博客主题 · 完整功能介绍与使用说明
适用版本：KX-Park 1.28.x ｜ 配套插件：KxParkKit 1.8.x（随主题持续更新）
最后更新：2026-10-23

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 本地资源，亮暗两套配色；代码块渲染成窗口样式（三色圆点 / 语言标签 / 行号栏 / 一键复制），资源按需加载，PJAX 切页也照样生效
• 二维码：本地 qrcode.min.js
• 字体：海报用的中文字体随插件打包

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

静态资源默认全部随主题下发；如果你有自己的图床 / CDN，也可以在设置里填一个「静态资源 CDN 前缀」把 CSS / JS / 表情搬到那里（详见第 12.7 节「静态资源 CDN 与图片上云」）。这是可选加速，不填也完全可用。

一致的交互语言

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

3. 功能总览

首页

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

文章页

• 封面图（字段指定，或自动取正文第一张图）；摄影集分类下的文章可单独关掉顶部封面横幅
• 图标化元信息：日期 / 作者 / 分类 / 字数 / 阅读时长 / 阅读热度
• 心情标记（自定义字段 mood）
• 阅读进度条（顶部随滚动前进）
• 自动目录（提取 h2/h3，可折叠）+ 悬浮目录（滚过正文目录后左下角出现「≡」，点开定位）
• 代码块窗口式外观：三色圆点窗饰条 + 语言标签 + 行号栏（两行以上才编号）+ 一键复制（复制 / 已复制 / 复制失败三态）
• 上下篇导航、标签、相关文章（同分类按热度，不足补最新）
• 文末版权声明（可开关自定义文案）
• 音频 / 视频 / 音乐卡片由短代码在正文任意位置插入（[audio] [video] [bilibili] [musiccard]，1.17.16 起媒体类自定义字段已移除）
• 互动条：点赞 / 打赏 / 分享（含生成海报）
• 图片灯箱：列表位加载缩略图省流量，点开灯箱仍看原图；正文图片渲染时压成 1600 宽 WebP，原图进 data-full 由灯箱按需加载
• 正文 <img> 支持 明暗自动换源：写 light-src / dark-src 即随明暗主题自动切换

页面模板

评论区

• 中文相对时间（「昨天 17:08」）
• IP 打码显示（124.116.244.*）
• 楼层号 #1
• 博主徽章
• 嵌套回复，就地展开，自动带「回复 @某人：」前缀
• 表情面板（阿鲁 / 泡泡 / 颜文字三组）；评论框内为富文本所见即所得：点表情直接显示成图，提交时再序列化回文本码，历史评论与无 JS 环境行为完全一致
• 每条评论可点赞（计数存站点缓存，访客本地防重复）
• 评论头像本地化缓存，五种头像源可选
• 垃圾评论拦截（由 KxParkKit 提供，规则与开关见 「插件设置项」（见第 10 节））

全站

• PJAX 无刷新导航 + 链接悬停预取 + 前进后退还原滚动位置；换页时会自动补发一次统计（百度 / GA4 / analytics.js / Matomo）
• 音乐播放器（悬浮唱碟，PJAX 切页不断播）：可自动解析网易云 / QQ 音乐歌单，支持滚动歌词与悬浮歌词条、三种播放模式、断点续播、跨标签页互斥、失败自动跳过；音质可切档（自动 / 标准 / 较高 / 无损 / Hi-Res）、进度条可拖动与键盘 ±5 秒、曲目关键词筛选、系统媒体控件（锁屏 / 通知栏）联动
• 弹出式灯箱（旋转 / 镜像 / 缩放 / 多图切换）
• 公告气泡（8 秒自动消失，访客关闭后本地记忆）
• 页脚一言（本地池随机，或 Hitokoto API 实时拉取）
• 本站已运行秒级实时计时
• 返回顶部、内容渐入、图片渐显、大图自动缩略图

后台

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

4. 安装与启用

环境要求

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

安装步骤

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

关于伴侣插件 KxParkKit

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

停用插件不会让站点坏掉：编辑器恢复系统默认；友链自动回退到主题设置里的文本（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 星空
• 头像地址：侧栏概览卡与瞬间作者头像
• 分享卡片图：在微信 / QQ 里分享链接时卡片上的缩略图，建议用正方形图
• 建站日期：用于封面统计与周年卡
• 社交按钮：每行 名称|链接

主题设置 → 内容流：

• 图库：每行 图片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 编辑器

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

• 默认单栏专注写作：预览默认关闭，点工具栏「开启实时预览」才分栏
• 内置 CodeMirror，代码编辑体验接近桌面编辑器
• 工具栏含加粗 / 斜体 / 标题 / 列表 / 链接 / 图片 / 表格 / 代码块 / 全屏等
• 全部资源本地化，不发任何外部请求
• 编辑区高度自适应视口（max(设置高度, 视口高 - 330px)），不再固定在小框里滚动
• 发布时自动把 Markdown 同步回原文 textarea，兼容草稿与自动保存
• 编辑器高度可在插件设置里调整（默认 560px）

预览里的短代码是近似渲染：插件在 markdown 源码层先把短代码替换成近似 HTML，再用 marked 自行渲染预览。它与前台的真实效果接近但不完全相同（例如可见性短代码在预览里不按登录态隐藏），以发布后的前台为准。

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

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]

实际效果：

⑥ 图片网格

四个断点分别设定每行几张图，可选统一宽高比。每格 = 一张图 + 紧随其后的说明行（图注）：说明有两种写法——用 [center]/[right] 包裹，或直接写一行文字跟在图片后面。图注可省略。

[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="1,2" bili="4x3"]

![](https://example.com/1.jpg)
[center]勒是雾都[/center]

![](https://example.com/2.jpg)
[center]火锅[/center]

[/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 9x16 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]

实际效果：

Typecho 官网轻量高效的博客程序十十年之约把博客坚持十年

多张的每行格式是 名称|描述|链接|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"]

实际效果：

typecho/typechoA PHP Blogging Platform. Simple and Powerful.PHP · 12457 · fork 2121

⑫ 引用文章

按文章 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]

实际效果（点播放试试，歌词会跟着滚动）：

父亲写的散文诗

许飞

0:000:00

歌词

歌词用标准 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] 这类写法放进反引号或代码围栏里就会原样显示，不会真的渲染成组件——本文档里的所有示例就是这么写的。

代码块怎么上色。 围栏写了具体语言（php、bash 这类）就按它上色；写的是 markdown 或者干脆没写，主题先做一次判断：内容是短代码或 HTML 注释时，按主题自带的「短代码」语法上色（方括号、属性名、属性值各有其色，右上角标签显示为「短代码」）；其余交给 highlight.js 自动识别，识别分数不够就按纯文本渲染——宁可不上色，也不猜成无关语言。两行以上的代码块会自动加行号栏，一键复制取的是不含行号的原文。

7.5 图床上传（KxParkKit）

开启 兰空图床上传（KxParkKit 设置，默认关闭）后，写作页「附件上传 / 拖拽 / 粘贴」的图片直接进你自己的兰空图床，正文里插入的就是图床 CDN 外链，站点不再存附件文件。

• 设置项：图床地址（你的兰空域名，如 https://img.example.com）、API 令牌、存储策略 ID（兰空要求显式传策略，留空会用默认策略导致「服务异常」）、上传相册 ID（留空则不归档）
• 上传前压缩（可选）：仅 jpg / png，最长边超过 2560px 等比缩小，JPG 质量 90 重编码；gif / webp 可能带动画，不做处理
• 失败行为：图床接口失败时本次上传直接报错可重试，不会悄悄退化成本地图片；错误详情记在插件 .cache/lsky.log
• 删除语义：在后台删除附件时，站点记录删除、图床上的原图保留（兰空 API 不提供删除端点）
• 历史上传的本地附件不受影响；关闭本功能后新上传恢复本地存储
• 与第三方 LskyUploader 插件的关系：本模块已覆盖它的全部能力，两者不要同时启用（会重复接管同一组钩子），插件保留在目录里仅为备查

8. 文章自定义字段

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

1.17.16 起移除了「外链音频 / 外链视频 / 音乐卡片」五组字段——这些能力已由编辑器工具栏的短代码 [audio] [video] [musiccard] [bilibili] 覆盖，写作时直接点工具栏按钮插入即可（旧文章里已填的字段值不再渲染）。

字段 vs 短代码，怎么选

1.16 时代「字段 vs 短代码」的双轨制已在 1.17.16 收敛为短代码单轨（媒体类字段已移除），封面/心情/置顶仍走字段。

9. 页面模板使用

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

瞬间

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

归档时光轴

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

友情链接

一页包含三块：

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

图库

按「摄影集分类缩写名」自动分组汇总：每篇摄影集文章作为一组相册（组标题可点进文章 + 日期 + 张数，组内三列瀑布流，点图开灯箱看原图），有 EXIF 的照片在图下展示一行拍摄参数。单页最多渲染 120 张，超出给「到分类页看全部」入口。分类未配置或该分类下暂无文章时，回退到主题设置的「图库（备用文本）」（每行 图片URL|标题）。

10. 友链申请与审核系统

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

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

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

10.1 前台申请

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

表单字段：站点名称 / 站点链接 / Logo（必填）/ 联系邮箱 / 站点简介 / 放置我方链接的页面地址（选填）/ RSS 订阅地址（选填）。

10.2 自动审核与复检（KxParkKit 1.5.x 起）

• 提交即检测：申请人可以填「放置我方链接的页面地址」（不填就检测其首页，两者必须同域）。服务端实时抓取该页，发现指向本站的链接（rel="nofollow" 与子域也算）→ 直接上架，双方邮件通知；没发现或抓不到（超时 / 拒绝 / 国内站屏蔽海外）→ 转入人工队列，原因会回给申请人
• 惰性复检：友链页被访问时静默触发一轮复检（每 6 小时最多一轮、每次查最久未检的 2 条，间隔天数可配）。只有「曾经检测通过、后来撤了链接」的站点会被标记异常；存量友链从不追缴反链。复检发现异常邮件通知站长
• 后台：每条友链有「检测」按钮即时复检；异常友链显示红色「异常」标记与「恢复正常」按钮；是否上架 / 下架始终由站长决定
• 抓取安全：仅 http/https 与 80/443 端口、最多 3 跳重定向、512KB 正文上限、DNS 解析后拒绝内网与保留网段（防 SSRF）；检测端点不接受外部传入地址，不能被当代理滥用

10.3 站长收信

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

收件人的解析顺序：

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

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

10.4 后台审核面板

后台 → 管理 → 友情链接。

面板包含：

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

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

10.5 插件设置项

插件设置页按功能分组，下面按组列出全部选项。

编辑器

友链申请

兰空图床

评论拦截

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

10.6 申请防护

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

11. 分享海报

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

海报内容

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

技术要点

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

关闭它

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

12. 性能、缓存与 SEO

12.1 缓存机制

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

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

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

12.2 图片优化

• 正文图片瘦身：文章 / 页面正文里的 <img> 渲染时改写为 1600 宽 WebP 缩略图（正文列宽约 1088px 的 1.5 倍，高分屏锐利），原图地址存进 data-full，灯箱点开哪张才加载哪张原图——摄影集文章单页体积从上百 MB 降到几 MB。跳过动图 GIF / SVG（转 WebP 会变静图）、相对路径本站附件与小图（端点自动退回原图）
• 封面同步瘦身：文章页封面同样取 1600 宽；网易云播放器封面加 ?param=300y300；友链 Logo 取 240 宽
• 大图自动缩略图（默认开）：Logo、封面、站点图标这类远端大图，会按实际显示宽度缩成 WebP 再输出。效果显著——一张 4MB 的 Logo 可以降到约 20KB。缓存 30 天
• 图片渐显（默认开）：懒加载图片解码完成后淡入，避免「半张图刷出来」的突兀感
• 明暗自动换源：给正文里的 <img> 写 light-src / dark-src 属性，即随明暗主题自动切换图片；只写一个时互相回退，不会出现空图
• 首屏优化：封面图 preload + fetchpriority=high，并对图片托管域名做 preconnect
• 列表位一律走缩略图：首页封面卡 / 图墙 / 图库 / 瞬间配图按格子宽度（480～960px）取图，不再直连 3000px 原图；灯箱打开时才加载原图

12.3 页面性能

• PJAX：站内跳转不重新加载整页，音乐播放器不中断
• PJAX 换页补发统计：统计代码原本只在首次整页加载执行一次，开启 PJAX 后站内跳转会在统计里整段丢失。现每次换页成功（含前进后退）都按各平台标准接口补发一次 pageview（_hmt 百度 / gtag GA4 / ga analytics.js / _paq Matomo），首屏整页加载不补发、因此不重复计数
• 链接悬停预取：鼠标悬停时提前拉目标页，点击后近乎瞬时
• 滚动性能：滚动回调用 requestAnimationFrame 合并，scrollHeight 缓存起来不在每帧重算
• 离屏跳过：长列表里靠后的卡片启用 content-visibility: auto，减少首屏渲染负担
• 毛玻璃降级：不支持 backdrop-filter 的浏览器、或系统开了「减少透明度」时，自动降级为不透明底色

12.4 SEO

主题内置输出：

• <title> 按页面类型自动拼装（分类 / 搜索 / 标签 / 作者 / 日期）
• 文章的 rel="canonical"（取纯路径、剥掉 s= 等随机查询，保留翻页参数；搜索页与 404 页输出 noindex, follow）
• 文章页 JSON-LD 结构化数据（BlogPosting：标题 / 日期 / 作者 / 封面），供搜索富摘要使用
• Open Graph 标签（og:type / og:url / og:title / og:description / og:site_name / og:image）与 Twitter Card
• RSS / Atom 的 rel="alternate"
• /sitemap.xml：由 KxParkKit 提供，覆盖首页 / 文章 / 独立页面 / 分类 / 标签。URL 全部按你的伪静态规则反解析生成，改伪静态不用改代码。只收录已发布、未加密、已到发布时间的内容
• /robots.txt：站点根的静态文件，声明 Sitemap 地址并挡掉 /admin/、/action/

分享到微信 / QQ 时卡片上的那张图：og:image 取当前页面的图——文章优先用自定义字段 cover，其次正文第一张图；首页、列表页、独立页面用「分享卡片图」（留空则依次回退到封面背景图、头像）。取到的图会由 assets/ogimg.php 裁成 478×478 的 JPEG 再输出，缓存在 cache/og/，所以 og:image 指向的是本站自己的地址：

• 微信要的是绝对 https 路径 + JPG/PNG，而站点封面多为横图、且常是 WebP。横图直接交给微信会被它居中裁方、两边各切一半，WebP 的兼容性也不确定，于是主题先把图处理好再给出地址
• 文章封面按「居中裁方」处理（照片填满方框更划算）；站点分享图按「整张缩进方框、余下留白」处理（宽版 Logo 不会被切掉笔画）
• 端点只服务主题登记过的图片，不能被当作开放图片代理；生成不了时会退回原图地址，卡片不会缺图

注意：卡片的最终样式由微信 / QQ 客户端决定，主题只能保证标签与图片合规。另外新域名首次在微信里传播可能被拦（提示「无法确认该网页的安全性」），这是微信对新域名的安全机制，到 https://urlsec.qq.com 提交申诉即可，一到两个工作日解除。

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

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

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

• 同一浏览器 6 小时内只计一次：浏览器 cookie 里记下已读文章的 cid 摘要（上限 40 个、6 小时），反复刷新不再重复计数
• 爬虫访问仍会计数
• PJAX 站内跳转不会触发（因为没有真正加载新页面）——所以站内流转不会虚增数字；但换页时会按各平台标准接口补发一次页面浏览统计（见 第 12.3 节「页面性能」）

写入不打扰访问：为避开每篇文章页都实时 UPDATE 数据库（曾在小事务下被放大到 3～7 秒），浏览量改为文件缓冲攒批：每次浏览只做一次带锁的文件读写，攒够间隔后才由某次请求批量合并进库，DB 写频率从「每浏览一次」降到「最多每分钟一次」。缓存目录不可写时自动退回实时写库，功能不受影响。

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

12.6 可访问性

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

12.7 静态资源 CDN 与图片上云

这两项都是「把静态体积搬离源站」的措施，都能显著降低源站带宽与首屏耗时，但默认不开，需要你自己准备图床 / CDN。

静态资源 CDN 前缀（设置 → 性能与外观）

填一个前缀（如 https://cdn.example.com/kxpark，不带末尾斜杠）后，主题的 style.css / main.js / qrcode.min.js / icons.svg / hljs/ / owo/ 表情 / foreverblog/ 徽标等纯静态资源都改从该前缀加载；留空则走本地主题路径。两个要点：

• 三个动态端点绝不外移：thumb.php（缩略图按需生成）、ogimg.php（微信分享图必须落本站）、music.php（音乐解析带会话）必须留在源站，别把它们同步到 CDN
• CSP 自动放行：主题的 Content-Security-Policy 原本写死脚本 / 样式限本源；填了前缀后会自动把该域名（协议 + 主机）动态加进 script-src / style-src，换域名无需再改代码
• 改了 CSS / JS 要 bump 版本号：静态资源 URL 带 ?v=（值 = MOFANG_VERSION），版本不动浏览器与 CDN 会一直拿旧文件

图片上云（缓存层切图床）

主题自带一层图片派生缓存：列表位缩略图（cache/thumbs/）与分享图（cache/og/）。它们可以整体搬到图床，让源站不再出图、改由国内 CDN 承担。实现方式是一张 上云清单 cache/bed/manifest.php（<?php exit; ?> 守卫 + JSON，命名空间 t/o/a/p/u）：

• 命中清单时，kxparkThumb() / kxparkShareThumb() / 表情地址函数直接返回图床 URL；未命中一律回退本地（新图还没迁移时行为不退化）
• 清单由主题目录下的上传脚本（用完即删）生成与合并，不改数据库——正文 / 封面里原本指向图床的地址不动，迁移的只是「派生缓存」这一层
• 删掉 cache/thumbs / cache/og 只会导致重新生成，不影响你图床里的原图

13. 常见问题

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

后台「外观」列表显示的名字来自主题 index.php 顶部的 @package 注释。目录名可以保持 kxpark 不变——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：上传的图片去哪了？删了附件图床上的图还在？

上传的图片由 KxParkKit 的兰空图床上传模块直传图床（开启后站点不存附件），正文里插入的就是图床 CDN 外链。在后台「附件」里删除时，只删站点的记录与本地文件，图床上的原图会保留——兰空 API 不提供删除端点，需要清理得登录图床后台手动删。详见第 7.5 节「图床上传」。

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

说明随插件打包的中文字体没被读到。检查 usr/plugins/KxParkKit/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 需要 KxParkKit 处于启用状态（它是插件注册的路由）。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 缩放显示，所以横版宽图最合适。

Q：音乐一直显示「解析中」/ 某首歌播不出？

播放器先把歌单链接解析成曲目列表，点播时再实时解析出直链（这一步走主题的 music.php 端点）。解析按三层顺序进行：① 自建音乐 API → ② 网易云 / QQ 音乐自解析（带后台授权 cookie）→ ③ 备用解析接口。① 正常时账号 cookie 完全不参与，只有自建 API 挂掉 / 配额用尽 / 该曲它拿不到时才动用账号。可能的原因：

• VIP / 已下架的歌：三层都拿不到完整版，最多给 30 秒试听，这是平台侧限制，任何方案都绕不过。想完整播放需在 KxParkKit 的音乐授权面板扫码登录网易云，或把账号 cookie 填进「网易云账号 Cookie」设置项（仅存服务器端）
• 自建 API 配额用尽（每天有上限，后台「自建 API 密钥」可换）：会自动回退到 ②，功能不中断，只是不再享有自建 API 的稳定性
• 选了无损却还是 320k：说明该曲在那家平台没有无损源。API 不降级，主题会取该曲可用的最高一档并播放，标题旁的音质角标显示的就是实际播到的档位
• 受限歌回落失败：确认「备用解析接口」没有留空
• 某曲失败卡住：开启「失败自动跳过」后会自动跳到下一首；只有全部曲目都失败才会停下

Q：播放器为什么切到别的标签页就暂停了？

这是跨标签页互斥的刻意设计：同一时间只允许一个标签页出声，其它标签页一旦检测到有页面在播放就会自动暂停本页。避免两个标签页同时放歌造成回声。

Q：改了主题的 CSS / JS，线上还是旧样子？

静态资源的 URL 带 ?v= 破缓存串，值等于主题版本号 MOFANG_VERSION。只改 assets/ 里的文件而不升版本号，浏览器与 CDN 会一直拿旧的缓存文件。正确做法：改完同步升 functions.php 的 MOFANG_VERSION 与 index.php 的 @version。若启用了「静态资源 CDN 前缀」，还要把改动同步到 CDN 目录，必要时在 CDN 控制台刷新 /assets/*。

Q：图片明明是好的，页面上却裂图 / 显示 520？

启用图片上云后，图片可能来自图床 CDN。先分清现象：520 一般是图床的 WAF 把来源 IP 临时封了（不是图没了），等一会或把来源服务器 IP 加进图床白名单即恢复；404 才是那张源图在图床被删；若本地一切正常、只有线上异常，多半是上云清单没命中（cache/bed/manifest.php 里缺这条），此时会自动回退本地，不会真的裂图。

Q：评论里输入的表情，为什么提交后变回了文字码？

这是期望行为。评论框的富文本层只负责输入时把表情显示成图，提交前会序列化回 (#名) / (:名) 文本码，服务端再统一渲染回图片。好处是数据格式全程不变：历史评论、无 JS 环境的纯文本框提交，渲染路径完全一致。

Q：链接发到微信里，显示的是一串网址而不是卡片？

先确认不是「直接粘贴」造成的：微信对粘贴进来的链接默认按纯文本处理，要先用微信内置浏览器打开过一次（长按消息 → 搜一搜 → 访问网页），之后分享才会走卡片。链接本身没问题的话，再看两件事——一是页面里有没有 og:image（指向 assets/ogimg.php 裁好的方图），二是站点能不能被微信的抓取器访问到（证书、CDN 拦截）。若是新域名被提示「无法确认该网页的安全性」，那是微信的域名安全机制，去 https://urlsec.qq.com 申诉。

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