v1.4.0 把导航栏做成了三级菜单,功能面基本齐了。所以这一版没加任何新东西——7 个提交里,1 个修 bug,4 个砍开销,1 个补文案,1 个发版。改动量也很小:12 个文件、+172 / −39。

但那个唯一的 bug 挺值得写:它看起来像「按钮坏了」,实际是一行本该防重复的标记写成了永久生效。

一、这一版做了什么

提交 类型 改动 一句话
663aab9 修复 5 文件 评论占位与运行时长文案接进语言包
073d1f4 性能 1 文件 没有进度条的页面不再每帧量高度
b173421 性能 1 文件 目录高亮不再每帧查 DOM
3502746 性能 5 文件 7.2KB 语言字典搬出 HTML
e7fd135 修复 1 文件 中英切换只能生效一次
0b0f6e4 性能 2 文件 纯自动广告模式不再加载 ads.js
e4bd8ee 发布 1 文件 版本号 1.4.1
文案归位

评论配置缺失的提示误用了搜索索引的文案;页脚运行时长把「天时分秒」硬编码在 JS 里。

三处空转

滚动、目录、广告三个脚本各自在做没必要做的事,逐个收掉。

字典外置

语言包从每页内联改成独立可缓存文件,单页 gzip 19.2KB 降到 16.3KB。

切换修复

永久标记改成按方向标记,「中→英」之后终于能切回中文了。

二、那个「只能切一次」的 bug

症状很好复现:点导航栏的语言按钮,中文变英文正常;再点一次想切回中文,整片文案纹丝不动。刷新页面又好了,因为刷新后是从头按语言重排的。

排查时先怀疑事件没绑上、语言没存住、字典反查失败——都不是。问题在翻译遍历本身:

JavaScript
1
2
3
4
5
6
// 修复前
texts.forEach(function (node) {
if (node.__xfmI18n) return; // 处理过的节点永久跳过
node.__xfmI18n = 1;
// …把 current 反查成 target,写回 nodeValue
});

打这个标记的初衷是对的。翻译的作用域容器是嵌套的(.site-header 里面还套着 .site-nav),同一个文本节点会被走到两次,不加标记就会「英→中」地被翻两遍,结果又变回英文。

问题在于标记是一次性布尔。第一次切换(中→英)把所有节点都打了标,第二次切换(英→中)遍历时发现「都处理过了」,整棵树直接跳过。

修法是把标记从「处理过没有」换成「按哪个方向处理过」:

JavaScript
1
2
3
var token = conv.id || 'once';
if (node.__xfmI18n === token) return;
node.__xfmI18n = token;

同一趟转换里 conv.id 不变,嵌套容器照样防重复;方向一变 token 就变,节点重新参与转换。属性遍历(title、aria-label 那些)同理,用的是同一个 token。

这类「防重复标记」的通用坑:标记的维度要和你真正想区分的维度一致。这里真正想区分的是「同一趟转换」,而不是「曾经转换过」——一旦记错维度,第二次操作就永远被挡在门外,而且表现得像功能没实现。

三、7.2KB 的字典不该跟着每个页面走

顺带发现的一个浪费:为了支持运行时切换,语言字典被拍平成「原文 → 译文」的大对象,内联在每页的 <head> 里,约 7.2KB(gzip 2.9KB)。而这份字典全站每个页面完全一样,等于每个访客每翻一页就重下一遍。

v1.4.1 把它挪到构建期生成的 /js/lang-data.js:

  • 新增 generator 输出这个文件,页面用 ?v=<hash> 引用,内容变了 hash 才变,缓存自然失效;
  • <head> 里只留定档需要的元数据(语言清单、默认语言、是否记忆),几百字节;
  • 字典文件放在 body 末尾、i18n.js 之前加载,执行顺序和原来一致。

这里有个细节值得记:?v= 里的 hash 和文件内容由同一个 helper 的进程级 memo 产出,从源头上保证两者同源。要是分别算,改一次字典忘了同步 hash,访客就会一直吃旧缓存——这种 bug 排查起来极其费时间。

单页 gzip 从 19.2KB 降到 16.3KB,看起来不多,但它是「每页都省」,而且省的是关键路径上的字节。

四、三处「每个滚动帧都在白干活」

剩下三笔都是同一类问题:脚本在不需要它的页面上照样跑。

滚动:onScroll 里无条件读 docEl.scrollHeight。读这个属性会触发一次同步布局计算,而列表页、归档页、标签页根本没有阅读进度条,量出来的高度没用。把这个读取挪进 if (progressBar) 分支,这些页面每个滚动帧少一次布局。

目录:文档页的目录高亮原来每帧对每个标题调一次 getElementById,setActive 还遍历全部目录项做 class 切换。改成初始化时一次性缓存标题元素数组,setActive 只摘掉旧的激活项、挂上新的——DOM 写操作从「目录项总数」降到常数级。文档页动辄几十个标题,这个差距不小。

广告:ads.js 只负责填充手写的 <ins class="adsbygoogle"> 单元。纯自动广告模式下没有任何待填单元,这个脚本每页跑一遍、查一圈、然后退出。加载条件从 load_script 收紧成 load_script && has_slot。

五、文案:两处硬编码

同一批改动里还有两个「英文站会露馅」的地方:

  • 评论配置缺失时的占位提示,误用了 I18N.searchError(搜索索引的文案),英文站会显示一句和评论区无关的话。新增 comments.config_error 语言键。
  • 页脚运行时长把「天 / 时 / 分 / 秒」写死在 JS 字符串里拼接,英文站永远显示中文单位;更麻烦的是它每秒重写 textContent,会把 i18n 已经替换好的结果冲掉。改成读 window.XFM.i18n 里的单位文案,并监听 xfm:langchange 重新渲染。

顺手做了两件小事:原来「每个运行时长元素一个定时器」合并成一个,页面隐藏时停表、切回来再续上,不在后台每秒唤醒。

六、升级与影响面

v1.4.1 没有配置项变化,也没有模板结构变化,全是 JS 与构建产物层面的调整:

  1. 必须重新构建,不能只换文件——/js/lang-data.js 是新生成的资源,旧产物里没有它。
  2. 用 npm 装的:npm update hexo-theme-xfm,或直接把 package.json 里的版本改成 1.4.1。
  3. 用 submodule 锁版本的(本站就是):本站已经指到 v1.4.1。拉下来后记得 hexo clean 再构建,否则旧的 public/ 里还留着内联字典的老 HTML。
  4. CDN / 反向代理:新增了一个静态文件路径,规则里如果按扩展名白名单放过 JS,不用动;按路径精确匹配的,记得放行 /js/。

如果站点自己改过语言包(在站点层覆盖 languages/*.yml),这次新增了 5 个语言键(comments.config_error 与 4 个运行时长单位)。缺了不会报错,只是这几处会回落到中文兜底文案。

七、写在最后

把 v1.4.1 的提交摊开看,主题在功能上已经停手了,做的全是已有功能的成本:一个切换 bug、每页 3KB、每帧一次布局、每帧几十次 DOM 查询。这些都不会出现在 README 的功能列表里,也没人会因为少了它们而不用主题——但它们决定了「用久了是什么感觉」。

版本号只走了 patch,改动也确实只有这么大。下一个版本想动的还是配置层:把那些「必须读源码才知道怎么写」的项,变成带注释的默认值。