架构与性能

中文 · English version

这一章讲「为什么快」,以及快的代价落在哪里。如果你只是想用,前九章就够了;想改内核、判断某个性能瓶颈能不能优化,这里有依据。

四个阶段

一次 xfm build 分四段,耗时统计也按这四段报:

阶段 做什么 1000 页耗时
扫描与解析 并行遍历目录、并行读取源文件、解析 front-matter ~690 ms
哈希 算每页的缓存键 ~15 ms
渲染 Markdown → HTML → 套模板(可并行) ~510 ms
写盘(冷构建) 建目录、写文件 ~2600 ms
写盘(重复构建) 比对内容,只写变了的 ~900 ms

写盘一直是最大的一块:1000 个目录的 mkdir 约 1.1 s,1000 个页面的落盘约 1.5 s,成本由文件系统元数据操作决定,在 Windows / NTFS 上尤其明显。想加速只能减少写盘量或换构建环境,优化渲染器没有意义。

扫描 + 哈希 + 渲染三项加起来不到 1.3 秒 —— 这才是生成器本身的开销。剩下的时间全在文件系统里,所以 v0.4.13 的优化方向是「少写」而不是「写快」。

Markdown 引擎:不建 AST

常见实现是「解析成 AST → 变换 → 序列化」,泛用但每一层都要遍历。xfm 的选择是线性扫描:块级逐行推进,行内用一次性正则,直接产出 HTML 字符串。

代价是扩展性受限(不能任意插入新的节点类型),收益是省掉了两轮完整遍历与大量对象分配。支持的块级元素足够覆盖技术写作:标题、段落、列表、引用、表格、代码围栏、分隔线、任务列表、脚注、提示容器。

几个实现上值得一提的细节:

  • 行内处理一次完成:加粗、斜体、代码、链接、删除线在一趟扫描里识别,避免反复 replace 造成的嵌套错乱。
  • 锚点同时产出:生成标题 id 的同时把 { level, text, id } 收集进 headings,右侧目录不需要再解析一遍 HTML。中文标题也能得到可读锚点,重名自动加序号。
  • 摘要另算:列表页要的摘要与阅读时长在扫描阶段用轻量正则剥离标记得到,不做完整解析 —— 因此列表页不需要等渲染。
  • 代码高亮内置:语言别名归一、未知语言降级为转义文本,不引第三方高亮库。

模板:编译成函数

模板不是每次渲染都解释,而是在第一次使用时编译成一个 JS 函数,之后只做字符串拼接。

Text
1
模板源码 → 词法扫描(识别输出、语句、注释三类标签)→ 生成函数体 → new Function

变量查找用 with(scope) 包住函数体,配合一个 Proxy 的 has 钩子:作用域里存在的名字走作用域,JS 内置对象(Math、JSON、console 等)交回原生作用域,未定义的名字返回 undefined 而不是抛 ReferenceError。

这个设计解决了一个很实际的问题:模板里写 {{ page.data.prev.title }},在没有上一篇时不该让构建崩掉。实现方式不是 try/catch(有运行时开销),而是编译期把成员访问改写成可选链 page?.data?.prev?.title —— 原生语法,零额外成本。

编译结果按模板路径缓存,源码变了才重新编译。dev 模式下改模板能立刻生效,靠的就是 mtime 比对。

worker 池

页面数达到 workerThreshold(默认 40)时启用 worker,条件还有一条:没有注册 markdown 钩子。

并发数怎么定:

Text
1
2
用户指定了 workers  →  min(任务数, workers, 32)
否则 → min(任务数, min(核数, 4), ceil(总源码字节 / 300KB))

两条约束分别对应两类浪费:

  • 核数上限取 4:worker 启动与上下文克隆要 30–60 ms 一个,8 核机器堆 8 个线程时,启动开销会吃掉并行收益;
  • 每线程至少 300 KB 源码:任务量太小时不开线程,主线程反而更快。

负载均衡用的是「按体积降序贪心装箱」:任务按源文件长度从大到小排序,依次塞进当前累计体积最小的桶里。比按页数平均更接近真实耗时分布 —— 一页 3000 行的文档和一页 50 行的短文,渲染成本差几十倍。

worker 之间只传必要数据:站点上下文序列化一次,模板在 init 阶段全部预编译,之后每个任务只传渲染所需的字段。结果回来时带 { key, html, bodyHtml } 三样。

一份实现,两个线程

早期版本在 worker 里重写了一遍「解析 front-matter → 渲染 Markdown → 组装上下文」,结果两份实现逐渐漂移,同一份源文件在页数少于 40 与多于 40 时产出不同:

  • 相对 .md 链接只在主线程被重写;
  • 日期格式一个走 UTC,一个走字符串截断;
  • page.data.prev / next 只有主线程有;
  • 阅读时长在 worker 里恒为 0,列表页永远不显示。

修复方式是把管线抽成 render.js,主线程与 worker 都调用它 —— 唯一差异只剩线程边界。现在产物逐字节一致,与页数多少无关。

这也是 transformHtml 钩子放在主线程补跑的原因:worker 只负责 Markdown 与模板,产物级的后处理(SEO 注入、HTML 压缩)等结果回来后统一做一遍,避免把插件序列化进子线程。

增量缓存的指纹

缓存键由六段拼接后哈希:

Text
1
layout | 主题指纹 | 配置指纹 | 源文件原文 | 列表摘要 | 相关文章

主题指纹是 layouts/ 与 partials/ 全部文件的哈希;配置指纹只取影响渲染的字段(theme、site、defaults、markdown)。

后两段是补过的坑:首页正文不变但文章列表会变,所以列表类页面额外掺入一份「文章清单摘要」(url + title + date + excerpt);相关文章是插件在 afterCollect 写入的跨页数据,不掺进去的话,别的文章改标签后本页推荐会留旧值。

缓存只跳过渲染,写盘仍然会发生 —— 命中缓存时从缓存里取 HTML 写出。但写盘阶段会先比内容:与旧产物逐字节一致的文件既不重写、也不建目录,所以 dist/ 永远完整,同时又省掉了重复构建里最贵的那部分。

写盘阶段的两个前提

v0.4.13 之前,重复构建和冷构建写盘一样慢,因为它做了两件没必要的事。两件都建立在一个容易忽略的事实上:dist/ 里不可能存在空目录。

  • 空目录的来历:一个目录只会因为里面的文件被删而变空。所以清理旧产物(pruneStale)不必每次全盘试 rmdir —— 只在本次构建真有文件被删时执行,且只扫这些文件的祖先目录(自深向浅、并行)。此前是 1000 个目录各试一次 rmdir,光这一项在 NTFS 上就要 3 s 左右。
  • 内容相同的文件不必重写:以前每次把所有页面刷盘(约 1.5 s)并为它们建目录(约 1.1 s),无论字节是否变化。现在按文件比对(先比大小、再比内容),一致就跳过;跳过的文件自然也不需要目录。静态资源用另一条判断 —— 大小相等且目标文件不早于源文件就放过,因此大图不会被读进来。

比对本身不是免费的:stat 加上读回来比一次约 0.8 s,仍不到重写成本的三分之一,所以这笔换算稳赚。

基准测试怎么读

Shell
1
npm run bench

bench 报的是分阶段耗时,不是单一总分。看的时候注意四点:

  1. 冷构建与重复构建要分开看。 bench.js 已经分成两项:冷构建先删掉 dist/(1000 页约 5–6.5 s),重复构建产物基本不变(约 2.8–2.9 s)。把两者混成一个中位数,既看不到写盘优化的收益,也判断不出真实上线耗时。
  2. 写盘占比是环境相关的。同样代码在 Linux + SSD 上写盘可能只要 800 ms,在 Windows + NTFS 上要 2600 ms,冷构建总时长差一倍以上,但解析与渲染阶段基本不变。
  3. 增量命中的「1 ms」 指的是渲染阶段跳过,整次构建仍有扫描与写盘成本 —— 写盘省不掉,但重复构建会因为内容一致而少写大部分文件。
  4. worker 不是越多越快。bench 里 2–4 个通常最优,堆到 8 个反而变慢,原因就是上面的启动成本。

测试

Shell
1
npm test     # 138 项,零依赖

测试直接跑真实站点构建,比对产物片段 —— 覆盖 Markdown 边界(嵌套与松散列表、惰性续行、列表项内块级内容、脚注回链与缩进、链接定义位置)、模板编译(未定义变量、可选链、过滤器错误)、URL 与 base 前缀、增量缓存失效条件、重复构建跳过写盘、删文后清理旧产物与空目录、CLI 的防护(非站点、BOM、脚手架冲突、--dir 越界)、插件加载与钩子顺序。不引测试框架,因此 node test/run.js 在任何 Node ≥ 18 环境都能跑。

设计上的取舍

选择 放弃的东西
零运行时依赖 不能直接复用 remark / unified 生态的插件
不建 AST 无法做任意语法扩展与结构化变换
模板编译成函数 模板表达式受限于 JS 语法,不能自定义 DSL
插件从内核拆出 新用户要自己装一圈插件才能补齐常见能力
线性 Markdown 极端边缘语法(如复杂嵌套引用)可能不如成熟实现严谨

这些取舍都指向同一个目标:构建时间与安装体积可预测。选择它,就等于接受这套边界。