几个月前有位读者私信我:好几篇文章里的代码块没了——不是乱码,是整块蒸发。页面能打开,标题和正文都在,唯独代码示例全都不见了。
我第一反应是源文件的问题。但本地一切正常:hugo server 起起来,代码块好好的。于是「本地能跑」成了最误导人的线索。
复现:同一份源,两种产物
这个站点是外部 CI(ESA)构建的,它钉死的 Hugo 版本是 0.146.0;我本机是 0.165。同一份 markdown,两个渲染器给出了完全不同的东西:
|
|
线上的渲染器把一个没有语言标记的围栏(开围栏后面什么都不写)当成了 GoAT 图的源,吐出来的节点是 goat svg-container,里面没有任何 <pre> / <code>。浏览器画了一张空 SVG,于是代码看上去就像凭空消失了。普通正文和带了语言标记的围栏都不受影响——这也导致这个 bug 藏了挺久:只有那些「没写语言」的块会丢。
具体 0.146 内部走了哪条渲染路径我没法拍胸脯说清,但观察到的产物是确定的:无语言标记的围栏在线上变成了 goat 容器。对修 bug 来说,真正要紧的是「空 info string 的渲染结果随版本漂移」这件事本身。
范围:全站几百处
出事那会儿,全站 99 篇文章里大约有 500 处裸围栏。三篇占了绝大多数:
| 文件 | 裸围栏数 |
|---|---|
| awesome-docker-get-start.md | 37 |
| nginx-rule.md | 29 |
| 2026-09-01-tech-radar-2026.md | 11 |
三个文件就 77 处(在 commit 292cb2f 里补齐)。但真正的问题不在三个文件,而在于:任何一个不带语言标记的围栏,都是渲染器版本一变就爆的地雷。
为什么本地量不出
因为这个 bug 是版本不一致,不是语法错误。同一份源文件:
- 在 0.165 上 → 渲染出
<pre><code>,看起来完美; - 在 0.146.0 上 → 渲染成 goat 容器,代码没了。
「在我机器上能跑」字面上为真,但也字面上没用。本地绿不等于线上绿。要看得到这个失败,唯一的办法是用部署同款二进制去构建——而我本机根本没有那个版本。
护栏:fence_lint 状态机
你既不可能肉眼扫 500 个围栏,也不能信「本地看着没问题」。我写了个 linter,把围栏当成状态机来解析,只数那一种真缺陷:开围栏且 info string 为空。
最容易踩的坑(也是我差点掉进去的)是用正则去匹配「行首只有三个反引号」的裸行。这是错的——因为收围栏本来就该是裸的。数裸行会把每一个合法的收围栏都判成问题,真缺陷反而淹没在噪声里。
正确的规则只有两条:
- 一个围栏行如果是在收一个已开的块,永远合法,裸不裸都行;
- 只有开围栏且 info 为空,才算「缺语言标记」这个缺陷。
|
|
现在对整个仓库跑一遍,输出是 篇=238 / 开围栏=1487 / 缺标记=0——站点长到 200 多篇,这道护栏依然兜得住。
修法
两件事:
- 给裸围栏补语言标记。
bash/python/json/yaml/text/toml,块里实际是什么就标什么。commit292cb2f把三篇大户清掉了(77 行改动)。 - 钉死构建版本。 教训不是「补一次标记」,而是「用和线上一样的二进制构建」。如果 CI 用的是和本地对齐的 0.165,我本机和生产的分叉在 push 之前就能看见。
一个好写法的例子:
|
|
坏写法就是把这个 bash 去掉,开围栏后面什么都不写——也就是「裸围栏」。线上 0.146 拿到这种块直接走 GoAT,代码就没了。本文为了不让自己触发这个 bug,下面所有示例围栏都带了语言标记;事故里那些坏块是连标记都没有的。
注意收围栏那一行本来就是裸的,这完全正确,也正是为什么你绝不能去数裸行。
三条能带走的
- 本地能跑不是上线证据。 构建 / 渲染版本必须和线上一致;CI 要用部署同款二进制,否则「本地绿」只是另一种静默失败。
- 空 info string 是缺陷,不是风格。 它决定渲染走哪条路径,不同版本会解释成不同东西。围栏没有语言标记,就该当 bug 修。
- 护栏按语义写,别按形状写。 「开围栏缺语言」才是真缺陷;数裸行会把合法收围栏全误报。护栏本身也要在同一个渲染版本下跑,否则它也会给你假绿。
这其实是可观测性的老道理换了个壳:最贵的失败,是看不见的那一种。这次「看不见」,是因为本地和线上的渲染器悄悄分了叉,而分叉本身不在我本地的任何日志里留信号——代码块是到了读者屏幕上才「消失」的。