架构与性能
中文 · 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 函数,之后只做字符串拼接。
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 钩子。
并发数怎么定:
1 | 用户指定了 workers → min(任务数, workers, 32) |
两条约束分别对应两类浪费:
- 核数上限取 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 压缩)等结果回来后统一做一遍,避免把插件序列化进子线程。
增量缓存的指纹
缓存键由六段拼接后哈希:
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,仍不到重写成本的三分之一,所以这笔换算稳赚。
基准测试怎么读
1 | npm run bench |
bench 报的是分阶段耗时,不是单一总分。看的时候注意四点:
- 冷构建与重复构建要分开看。
bench.js已经分成两项:冷构建先删掉dist/(1000 页约 5–6.5 s),重复构建产物基本不变(约 2.8–2.9 s)。把两者混成一个中位数,既看不到写盘优化的收益,也判断不出真实上线耗时。 - 写盘占比是环境相关的。同样代码在 Linux + SSD 上写盘可能只要 800 ms,在 Windows + NTFS 上要 2600 ms,冷构建总时长差一倍以上,但解析与渲染阶段基本不变。
- 增量命中的「1 ms」 指的是渲染阶段跳过,整次构建仍有扫描与写盘成本 —— 写盘省不掉,但重复构建会因为内容一致而少写大部分文件。
- worker 不是越多越快。bench 里 2–4 个通常最优,堆到 8 个反而变慢,原因就是上面的启动成本。
测试
1 | npm test # 138 项,零依赖 |
测试直接跑真实站点构建,比对产物片段 —— 覆盖 Markdown 边界(嵌套与松散列表、惰性续行、列表项内块级内容、脚注回链与缩进、链接定义位置)、模板编译(未定义变量、可选链、过滤器错误)、URL 与 base 前缀、增量缓存失效条件、重复构建跳过写盘、删文后清理旧产物与空目录、CLI 的防护(非站点、BOM、脚手架冲突、--dir 越界)、插件加载与钩子顺序。不引测试框架,因此 node test/run.js 在任何 Node ≥ 18 环境都能跑。
设计上的取舍
| 选择 | 放弃的东西 |
|---|---|
| 零运行时依赖 | 不能直接复用 remark / unified 生态的插件 |
| 不建 AST | 无法做任意语法扩展与结构化变换 |
| 模板编译成函数 | 模板表达式受限于 JS 语法,不能自定义 DSL |
| 插件从内核拆出 | 新用户要自己装一圈插件才能补齐常见能力 |
| 线性 Markdown | 极端边缘语法(如复杂嵌套引用)可能不如成熟实现严谨 |
这些取舍都指向同一个目标:构建时间与安装体积可预测。选择它,就等于接受这套边界。
评论