侠客行 · xiakexing｜一款把「江湖」写进代码的 Typecho 主题

墨黑为骨，宣纸为肤，朱砂为血，松烟为气。
不依赖任何插件，不请求任何外部资源 —— 整卷江湖，都装在一个文件夹里。

如果你刚接触 Typecho，或者只是想给自己的博客换一张「有味道」的脸，这篇介绍为你而写。它不讲晦涩的代码，只讲三件事：它长什么样、它能做什么、你怎么把它装上去。

一 · 先说结论：它是什么

侠客行（xiakexing） 是一款武侠风的 Typecho 主题，当前版本 v1.5.1。

它最特别的地方，是不靠外链活：

按官方 README 的说法：「只有把『批注头像』切到 Gravatar 时，才会请求一次 gravatar.com」。换句话说，只要你保持默认设置，这个站可以断网打开、离线存活。

对新手最实际的好处是：不会因为图床挂了、CDN 被墙、字体服务收费而变丑。

二 · 武侠的寓意：为什么它叫「侠客行」

一个好主题的名字不是随便起的。侠客行把整站拆成了四样东西，每样都对应武侠里的一件物事：

再往细里看：

• 首页是卷轴：整页纵向滚动，文章是一枚枚竹简，竹简上有竹筋竖纹、编绳装订痕、汉字编号（壹、贰、叁）。
• 导航是匾额：分类不叫分类，叫门派；导航条上的每一项都是一方匾额（刀剑录／药典／诗酒行／夜行记）。
• 评论是朱批：评论区叫「侠客批注」，朱砂色边框，像在纸上用朱笔圈点。
• 头像即面具：每位留言者都戴一张面具 —— 这是他在江湖中的身份。
• 侧栏是舆图：侧栏叫「江湖地图」，山水舆图上钉着四盏驿站灯：驿站·归档、茶馆·批注、名录·友链、藏经·题签。
• 404 是残阳：找不到页面时，一雁南去、残阳如血，配一句「江湖路远，此地无碑」。
• 文末有短句：每篇文章结尾自动缀一句门派短句（可按门派配置，也可用自定义字段单独覆盖）。

一壶浊酒，半卷残书。愿这卷轴，装得下你的江湖。

三 · 外观设计：从卷首到页脚

3.1 配色与纸面

• 四种主色全部可在后台修改（题字、朱砂、墨黑、宣纸、松烟），改完实时注入 CSS 变量，全站跟着变。
• 纸面不是纯色：宣纸肌理（SVG 噪声）+ 淡墨晕染（径向渐变）+ 云纹隐现（SVG 平铺）三层叠成，全部是内联 data URI，不下载任何图片。

3.2 字体

• 主标题走楷体栈（Kaiti SC / STKaiti / KaiTi / 楷体），正文走宋体栈（Songti SC / STSong / SimSun / 宋体）。
• 全部取系统字体，不加载远程字体 —— 这是「零请求」的一半功劳，也是首屏快的原因。

3.3 纹样

竹影、孤雁、残阳、刀剑轮廓、云纹、印章，都是内联 SVG，而且只做边缘点缀，绝不压住正文。后台可以逐项开关（五个装饰元素单独控制）。

3.4 逐屏速览

3.5 三张独立页面模板

新建独立页面时，右侧「自定义模板」里可以挑：

另外，只要独立页面的缩略名分别是 about、links，不选模板也会自动套用对应卡片页。

名录页的排布是手机两列起、宽屏自动增列：每张名刺帖顶上钉着一枚朱砂顶针，右肩是 30px 的首字方印（微微歪 4°），帖与帖交替微倾，像有人把帖子一张张贴满了整面墙。鼠标移上去（或键盘 Tab 到）时，帖子会扶正、上浮、印章归正、钉影加深，露出一副「请进」的姿态。新加的朋友（名录行末写 新）会在名号旁多盖一枚朱砂「新」标，榜额上也会多吐一句「新朋 N 位」。

四 · 侠客面具：本版的重头戏（v1.5.0 扩至二十款）

面具是这版的重头戏：从 6 款起步，1.4.0 扩到 12 款，1.5.0 再扩到 20 款。每张都由「眉形 + 额饰 + 颏饰」三层叠成，20 款组合互不重复 —— 你从纶巾、镖带、道髻、酒匏、折扇、莲冠、角弓、棋枰里，一眼就能认出对方的身份。

4.1 二十款面具一览

12–19 号为 1.5.0 新增；0–5 号是 1.3.0 的老面孔，6–11 号是 1.4.0 的旧账，路径与次序一字未动。

每一款都由「眉形 + 额饰 + 颏饰」三层叠成，12 款组合互不重复。

4.2 访客怎么用

在评论框（「落笔」）里，有一栏叫 「择一面具」：点一下那条触发条，面具谱便自屏幕底部升起 —— 二十款分四行排开（窄屏五列，宽屏六列／八列），点哪张，触发条上的预览与名号就换成哪张，随即自动收起。另有一条底注：

批注里露的那张脸，随这条批注一同入档

这句话是认真的：你选了哪张，这条批注就永远戴着哪张，翻回来看到的还是它。

4.3 没选面具的人呢

没选的人，系统按名号推演 —— 同一个名字，永远得到同一张脸。

升级不会打乱老批注的脸。 推演的基数被固定为旧版的 6 款（xiake_mask_legacy_count()），所以从 v1.3.0 升上来的站，所有老评论的面貌一字未变；新面具只在你主动挑选时出现。若存档里的编号越了界（比如手改过数据库），也会自动退回名号推演，不会白脸。

4.4 弹出选择：为什么不是铺一张大网格

1. 不改数据库结构。 Typecho 的评论表没有自定义字段，主题借用了 agent 这一列 —— 它是唯一「会入库、但前台后台都不显示」的自由文本列。所选编号以 xkxmaskN 记在它的末尾，读取时再解析回来。
2. 不阻断评论。 万一钩子没挂上、字段被截断、编号异常，面具只会退化成「由名号推演」，绝不会让评论提交失败。

五 · 特色亮点：十件值得说的事

1. 零外链、零请求：字体、纹样、头像全部自给，断网可开。默认设置下全站不发一个外部请求。
2. 不装插件、不改内核、不动数据库：解压即用，卸载即净。
3. 二十款自绘面具：不依赖 Gravatar，隐私友好，还好看。
4. 移动端优先：窄屏自动转单行卷轴，触控目标够大，正文 15–17px。
5. 无障碍：保留「直入正文」跳转链接、键盘焦点样式、aria-expanded / aria-hidden 标注，并尊重系统的「减弱动态效果」设置（prefers-reduced-motion）。
6. 可打印：打印时自动隐去匾额、侧栏、批注与纹样，只留纸与字。
7. 江湖时辰与节气：页脚按服务器时间推算十二时辰与当前节气（采用通用寿星公式，2000—2099 年精度最好）。
8. 三张现成页面模板：名录、关于、武林谱，建好页面改个缩略名就能用。

9. 弹出式面具谱：自屏幕底部升起一栏「面具谱」，二十款任择其一。移动端不外溢、不添滚动条，键盘 Esc、点遮罩、「收起」三处皆可关；脚本未就绪时面具谱平铺在表单里，无 JS 也能选。
10. 文章置顶 · 朱砂「荐」印：后台「江湖令 · 置顶卷」填 cid 或 slug，或在文章自定义字段里加 sticky = 1，该篇便排到首页首屏最前，卡片右上角盖一枚朱砂「荐」印。

六 · 下载与安装（新手向，逐步照做）

6.1 环境要求

• Typecho 1.1.x / 1.2.x
• PHP 5.6 及以上（代码已在 PHP 7.x / 8.x 语法范围内编写）
• 不需要任何插件

6.2 四步装好

第 1 步：拿到主题包

下载 xiakexing-v1.5.0.zip，解压。你会得到一个名为 xiakexing 的文件夹。

第 2 步：放进 usr/themes/

用 FTP／宝塔面板／SFTP，把 xiakexing 整个文件夹放进 Typecho 根目录下的 usr/themes/ 里。放好后路径应该长这样：

你的站点根目录/
└── usr/
    └── themes/
        └── xiakexing/
            ├── index.php
            ├── style.css
            ├── functions.php
            └── ...

注意：️ 新手最容易踩的坑：不要把 xiakexing 外面那层目录一起传进去，否则会变成 usr/themes/xiakexing/xiakexing/index.php，后台认不出这个主题。判断标准很简单：index.php 必须直接躺在 usr/themes/xiakexing/ 里面。

另外请保持文件夹名为 xiakexing（改名后主题的兜底资源路径会失效）。

第 3 步：后台启用

登录后台 → 控制台 → 外观 → 找到「侠客行」→ 点击启用。

第 4 步：逐项配置

后台 → 外观 → 设置外观 → 打开「江湖令」面板，按下面的清单走一遍即可。

6.3 升级（已是旧版站点）

直接用新包覆盖 usr/themes/xiakexing/ 整个目录即可。本次只动了 functions.php 和 style.css 两个文件，也可以只覆盖这两个。不改内核、不动数据库、无插件依赖，回滚就是恢复备份目录。

七 · 首次上手：五步配置

装好之后别急着写文章，先花五分钟配这五样，效果立刻不一样：

1. 题字与匾额：填站名与匾额小字（默认「侠客行 / 落笔皆是江湖」）。
2. 四色：朱砂、墨黑、宣纸白、松烟灰。想更冷就调低朱砂饱和，想更亮就调高宣纸白。

3. 建分类，用武侠语汇：主题不强制，但推荐

   刀剑录　药典　诗酒行　夜行记　江湖志

   分类在这里叫「门派」，导航会自动呈现为匾额，归档标题写作「某派门下」。

4. 写几条门派短句：格式 门派名|短句，一行一条。文章末尾会自动缀上对应的一句；没命中就按文章编号稳定取一句。
5. 挂上江湖名录（友链）：格式 名号|网址|一句评，一行一条；想让哪一位在帖上多盖一枚朱砂「新」标，就在行末再加一栏写 新（名号|网址|一句评|新），三栏的老写法照旧可用。然后新建一个独立页面，缩略名填 links，不选模板也会自动变成名刺帖陈列墙。

可选：换掉匾额上的「侠」字

后台「江湖令 → 匾额印图」填一个图片地址，网站的匾额就以图代印；留空则自动去找 assets/img/logo.svg（或 .png / .jpg / .jpeg / .webp）；都没有，就回到朱砂「侠」印。三级兜底，不会留白。

自定义字段（写在文章的「自定义字段」处）

常用的三枚：thumb 填封面图地址；mantra 填一句门派短句；1.5.0 起多一枚 sticky —— 值填 1，这篇就置顶（等价于在「江湖令 · 置顶卷」里写上它的 cid 或 slug）。

八 · 常见问题 FAQ

Q1：评论提交了却不显示？
本站 v1.3.0 起已修掉这个经典问题。根因是 Typecho 1.2 之后开启了评论防垃圾校验，而回批框的 id 必须与内核的 respondId（形如 respond-post-12）一致，令牌才塞得进去。主题已把 id 交还内核口径，表单里还内置了一枚兜底令牌，无 JS 也能提交。若你仍在旧版遇到此问题，升级到 1.3.0 以上即可。

Q2：搜「寻」跳到主页或错页？
旧版空关键词会被内核拼成 /search//，匹配不上搜索路由。现版本：输入框加了必填；提交时直接把关键词编码后跳到搜索页，绕开中间那次 302。

Q3：侧边栏有一条滚动条，很丑。
现版本已隐去侧栏滚动条的描边（scrollbar-width:none 等），滚轮与触摸照旧可滚，只是不再画出那条线。

Q4：能完全断网运行吗？
能。只要「批注头像」保持默认的侠客面具（而不是 Gravatar），全站不发任何外部请求，字体与纹样全部本地内联。

Q5：节气/时辰不准？
节气是推算值（通用寿星公式，2000—2099 年精度最好），个别年份可能差一日，属正常。时辰按服务器时间推算，与访客本地时区可能不同，可在服务器时区设置里调整。

Q6：能不能改面具数量／换成自己的图？
面具是 functions.php 里 xiake_avatar_svg() 的三组数组（眉形／额饰／颏饰）生成的。加面具只需往数组尾部追加元素并把 xiake_mask_count() 的返回值改大；注意不要动已有元素的顺序，否则会打乱老批注的面貌。若想彻底换成照片头像，把「批注头像」切到 Gravatar 即可。

九 · 版本与升级

• v1.5.1（当前）：友链页改版为名刺帖陈列墙——以竖版名刺取代横排名帖：顶中一枚朱砂顶针、右肩一方 30px 首字方印（-4°）、帖与帖交替微倾（-1.1°／0.9°／-0.35°），悬停扶正上浮、印归正、钉影加深；手机两列、≥620px 三列、≥1180px 四列（真机自 900px 起有右侧「江湖地图」栏，四列故而后移）；名录制式加一栏可选「新」，榜额出「新朋 N 位」；投帖区改为三枚 chips。旧名帖类名一律不保留。
• v1.5.0：面具库 12 → 20 款（新增捕快／游医／说书人／女冠／刀疤客／猎户／棋士／更夫）；「择一面具」改为弹出式面具谱（移动端底部弹层，无 JS 时平铺兜底）；新增文章置顶——后台「江湖令 · 置顶卷」或文章自定义字段 sticky = 1，置顶卷排首页首屏最前并盖朱砂「荐」印；卡片形制抽成 xiake_slip_markup() 共用。
• v1.4.0：面具库 6 → 12 款（新增书生／镖师／道人／酒客／剑仙／女侠）；旧六款绘制路径与次序一字未动；推演基数固定为旧六款，老批注面貌不变；评论框面具栅格适配十二款。
• v1.3.0：修复前后台评论都不显示；「寻」直达搜索页；隐去侧栏滚动条；友链页重设计为名帖册；匾额印图可配；评论框首次加入面具自选。
• v1.2.x：组件池清理、PHP 8 Throwable 兜底、批注显示链路等一批修复。

升级方式：覆盖整包即可，或只覆盖 functions.php 与 style.css。

自检：在主题目录下执行

node tools/selfcheck.mjs

可复核版本号一致性、关键函数存在性、面具库规模、名刺帖接线与括号配平（1.5.1 共 80 项断言）。

十 · 版权与致谢

• 主题基于 Typecho（typecho.org）开发，遵循其生态惯例。
• 全部纹样、面具、图标均为主题自绘内联 SVG，不引用任何第三方素材站资源。
• 页脚会自动附上 Typecho 与主题署名，这是对开源作者的尊重，建议保留。

一壶浊酒，半卷残书。愿这卷轴，装得下你的江湖。