站点这条线是三条产线里最成熟的一条:每次 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 工作流的顺序:
- 内容编译 —— 读
docs/下的所有 markdown 与 HTML,
套好前置元数据,写进source/_posts/,
同时把图片复制到source/images/,并现写现生成几个页面
(分类总览、标签总览、关于我,以及已删除落地页留下的重定向页)。 - 素材搬运 —— 把
node_modules/里的第三方资源搬进source/lib/:
Prism 语法高亮、Mermaid、Gitalk、Font Awesome 的字体。
主题是按固定路径引用它们的,所以得在渲染前搬进产物目录。 - 渲染 ——
hexo generate按年/月/日/<slug>/的规则
把每一篇渲染成静态页面。这期间会跑scripts/下的四个扩展:
Mermaid 图渲染、HTML 文章处理、智能摘要、图片尺寸标注。 - 部署 —— 把
public/推上去。 - 评论预创建 —— 给所有新文章预创建评论用的 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/,
那不就不用编译脚本了吗?
不行,有三个原因:
- 推导逻辑需要跨文章计算。 分类名要从目录索引文件里解析、
祖先目录要级联、链接要改写成带日期的绝对地址——
这需要一次全局遍历,Hexo 的过滤器拿不到完整的目录树视图。 - 契约校验需要「先编译再校验」。 校验对象是编译后的内容单元,
因为那才是下游真正会用的东西。跳过编译去校验,等于校验一份没人会读的文件。 - 产物目录必须可丢弃。
source/和public/每次 CI 现生成,
本地能放心删掉重来,不会有「上次生成的东西混进来」的脏状态。
多一个编译脚本,换来源码树与产物树彻底分离,
以及「删掉 source/ 重跑一遍,结果都一样」这条性质。