从母稿到页面


 TL;DR
docs/ 是唯一真相,编译脚本生成 Hexo 源,Hexo 渲染成静态页;主题定制靠按标记注入而不是改主题;日期来自 git 历史——它会漂移。
难度 中等

站点这条线是三条产线里最成熟的一条:每次 push 到主分支,
构建加部署端到端十几分钟,线上就更新了。这篇讲清楚这条链路到底发生了什么,
以及它为什么不是「把 markdown 扔进 Hexo 的 source 目录」那么简单。


一、三个边界

整个仓库对「站点的组成」只有三条硬边界:

  • docs/ 是内容。 所有 markdown 和 HTML 都在这里,只有这里。
  • themes/matery/ 是样式。 模板、样式表、脚本、静态资源。
  • tools/ 和 scripts/ 是适配层。 负责把内容喂给 Hexo,
    再把渲染产物套上主题。

配置也是分开的:根目录的 _config.yml 是 Hexo 自己的,
_config.matery.yml 是对主题配置的覆盖。
要改主题的默认值就改后者——不要直接改主题自带的配置,
因为主题升级会把它冲掉。

另外两个目录 source/ 和 public/ 都在忽略列表里,每次 CI 现生成。
手工往 source/_posts/ 里塞东西没有意义:commit 推不上去,CI 还会整个重写。


二、一次 push 之后发生了什么

按 CI 工作流的顺序:

  1. 内容编译 —— 读 docs/ 下的所有 markdown 与 HTML,
    套好前置元数据,写进 source/_posts/,
    同时把图片复制到 source/images/,并现写现生成几个页面
    (分类总览、标签总览、关于我,以及已删除落地页留下的重定向页)。
  2. 素材搬运 —— 把 node_modules/ 里的第三方资源搬进 source/lib/:
    Prism 语法高亮、Mermaid、Gitalk、Font Awesome 的字体。
    主题是按固定路径引用它们的,所以得在渲染前搬进产物目录。
  3. 渲染 —— hexo generate 按 年/月/日/<slug>/ 的规则
    把每一篇渲染成静态页面。这期间会跑 scripts/ 下的四个扩展:
    Mermaid 图渲染、HTML 文章处理、智能摘要、图片尺寸标注。
  4. 部署 —— 把 public/ 推上去。
  5. 评论预创建 —— 给所有新文章预创建评论用的 issue,
    这样读者第一次留言不用等。

主题补丁在 CI 里是单独一步(在内容编译之后、渲染之前):
tools/patch-theme.py 对主题文件做小手术——追加 SEO 与分享用的 meta、
注入「相关文章」区块、访问量计数器、分享按钮。


三、内容编译这一步做了什么

这是整条链路上最重、也是唯一有「判断」的一步。

剥掉首个一级标题。 正文里的第一个 # 标题 会被去掉——
标题要写进前置元数据,页面模板用它渲染成大标题。
没有标题就退化成文件名。

重写图片路径。 docs/ 里的图片引用是相对当前文件的,
编译之后图片被搬到了统一的位置,所以引用要跟着改。

重写站内链接。 最容易被忽略、也最重要的一步:
docs/ 里的相对链接(比如 ./另一篇/)在编译产物里必须变成
能被点开的绝对地址——最终 URL 带着日期和 slug,
写相对链接十有八九会 404。

重建前置元数据。 上一篇讲的契约就是在这儿执行的:
推导字段算出来,透传字段原样搬过去,未声明的字段丢掉。

决定什么不是文章。 隐藏目录不进产物;工程性质的目录名
(tests、test、fixtures、pipeline、build、out 之类)整棵不进产物。

这条规则按文件数命中 0 个——但 docs/ 下还留着一棵工程目录
(docs/src/test/,Linux 内核模块的试验目录),里面没有会被当文章的文件。
它是防回归守卫,不是修复手段。


四、中文分类名是从哪长出来的

这是这套构建里最巧的一处设计。

站点的 URL 用英文 slug,页面上显示的分类名用中文。这两件事由同一个文件决定:
分类目录下的 _index.md。

  • 顶层目录的 _index.md 里的 title:,就是这个顶层分类的中文名。
    目录叫 life/,标题写「人生」,那么站点上这一类的名字就是「人生」,
    文章页的分类链接指向它。
  • 子目录的 _index.md 里可以写 cascade.categories,
    声明这一层往下所有文章都带上哪个分类。
    编译脚本从文章的路径往上找,收集所有祖先目录声明的分类名,去重后写进元数据。

少了这个文件会怎样? 分类名就退化成目录名本身——
URL 变成英文 slug,页面上也没有中文名字。
而它不会报错:文章照发,只是分类页的名字很难看。
这种「静默降级」是构建链路上最坏的一类问题,所以这个文件是硬要求。

顺带一提:分类索引文件本身不会变成一篇文章。
它只是分类元数据的载体。编译脚本遇到它会直接跳过。


五、主题补丁:为什么不直接改主题

主题自带的模板不能直接改——升级会覆盖。
但这个站又不是原封不动用主题的:文章页要显示 TL;DR 和难度星级,
要显示「相关文章」,要显示访问量,要有分享卡片。

做法是按标记注入:补丁脚本在模板的特定位置插一对注释标记,
然后把定制内容写在这对标记之间。脚本是幂等的——
跑第二遍不会插出两份,跑第三遍也不会。

这个取舍很明确:

做法 代价
直接改主题文件 每次升级都要重做一遍,冲突无解
fork 一份主题自己维护 主题升级要自己合并,几十个文件逐个对
按标记注入 升级后重跑一次补丁,冲突面只有标记位置

第三种最省事,代价是补丁脚本要一直维护:
主题升级若改了标记附近的结构,补丁就会插错位置——
所以它跑的时候要失败得很响,不能插不进去还当成功。


六、CI 门禁:让机器守着规则

内容类的规则最怕「靠人记」。能被机器检查的,就交给机器。
但「机器守着」和「机器拦着」是两件事:

闸门 在哪 查什么 违规时
内容契约校验 契约工作流 前置元数据的字段名、类型、长度、枚举取值 工作流失败,不发版
契约层与适配器测试 契约工作流 切片、出包、草稿箱规则 同上
站点守卫 守卫工作流 渲染产物上的断言(页脚、链接、卡片摘要……) 同上
产物自检 构建工作流 期号区块、首页 tab、卡片摘要 同上
格式校验 没接进 CI 围栏有没有标语言、标题层级有没有跳级、链接指向的文件在不在 只报告,不拦

前四道都是硬的:任何一道不过,站点就不发布。这是有意的——
契约违规要让「这篇发不出去」变成一句明确的失败,
而不是一篇悄悄跑偏的文章。

最后一道是工具齐了但没接进 CI:全站几百个文件里有一批历史遗留问题,
硬闸门会立刻卡死所有发布。规格里为此写了一条对策——
「只校验改动文件,未知字段只告警不拦」——但它目前还只是设计意图。
所以现状是:新文章有硬约束,老债不挡路,
但两者的界限目前靠人划。


七、这条线上真实踩过的四个坑

坑一:日期来自 git,所以搬一次家就会漂

文章的发布日期不是作者填的,是从 git 历史里取的
「该路径在所有分支上的最早提交时间」。

这个设计的好处是新增文章零配置——写完提交,日期自动有了。
但它有个致命的前提:这个路径的历史必须是连续的。

用 git mv 把一批文章搬到新目录之后,新路径的最早提交就变成了
「搬运」那一次。于是全站几百篇文章的日期同时变成搬运日,
一起跳到「最近发布」的顶部,把首页冲垮。

更隐蔽的是连带效应:旧链接的重定向页也要用日期拼 URL,
日期一漂,重定向页就指向了一个错误的地址,旧链接照样 404。

对策:搬家时把每篇文章的原始日期按新路径固化进一张覆盖表,
日期查询先查表再查 git(现有二十多条,都是历史搬家留下的)。
但「迁移前后逐篇比对日期」的自动断言还没写成脚本——
设计文档里列成待办。几百篇文章共用同一个导入日期,抽查根本看不出来。

坑二:时区被算了两次,日期整整差一天

git 给出的时间戳带时区偏移(+0800)。
CI 容器里 TZ=UTC,而 Hexo 生成日期路径时会把偏移再应用一次——
于是跨过 UTC 午夜的日期会整体差一天:
上午十点四十的文章,页面上显示的是前一天。

修法是两头一起改:编译脚本写不带偏移的墙上时间字符串,
同时把站点配置里的 timezone: 留空。

教训是:时间、编码、路径这三样的默认值假设,
在不同环节经常对不上
,而症状(日期差一天)离原因(时区被算两次)很远。

坑三:别把绝对链接写进文章里

文章里写 /2026/07/03/某篇文章/ 这种写死日期的绝对地址,
一旦日期被重算(见坑一),链接就指向不存在的地址。

站内链接一律写相对路径,让构建脚本在编译期替换成真正的地址。
写文章的人不需要知道最终 URL 长什么样。

坑四:以为排除规则能解决「什么不是文章」

曾经的版本里,一个故意写坏的测试样本被当成公开文章发布到了线上,
还进了站点地图。这件事的根因不是「排除规则不够多」,
而是内容目录和工程目录住在同一棵树里。

对的方向是物理分离:工程内容搬出内容树,发布路径只扫内容树。
但这件事还没做完——docs/src/test/ 这棵 Linux 内核模块的试验目录
还躺在内容树里,眼下靠排除规则挡着(里面没有 .md,
所以规则按文件数命中 0,但目录本身还在)。

排除规则因此既不是修复手段,也不只是防回归守卫,
它是物理分离完成前的临时防线:等那棵树搬走,才退回到防回归守卫的位置。

这个坑的教训比它的修复更值得记:
当一条规则的命中数是 0 时,它要么是多余的,要么是还没被需要。
判断它属于哪一种,要看它防的是哪一类事故。


八、为什么不让 Hexo 直接吃 docs/

一个很自然的想法:Hexo 的源目录可以配置成 docs/,
那不就不用编译脚本了吗?

不行,有三个原因:

  1. 推导逻辑需要跨文章计算。 分类名要从目录索引文件里解析、
    祖先目录要级联、链接要改写成带日期的绝对地址——
    这需要一次全局遍历,Hexo 的过滤器拿不到完整的目录树视图。
  2. 契约校验需要「先编译再校验」。 校验对象是编译后的内容单元,
    因为那才是下游真正会用的东西。跳过编译去校验,等于校验一份没人会读的文件。
  3. 产物目录必须可丢弃。 source/ 和 public/ 每次 CI 现生成,
    本地能放心删掉重来,不会有「上次生成的东西混进来」的脏状态。

多一个编译脚本,换来源码树与产物树彻底分离,
以及「删掉 source/ 重跑一遍,结果都一样」这条性质。


九、相关阅读


文章作者: growdu
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 growdu !
  目录