几个月前有位读者私信我:好几篇文章里的代码块没了——不是乱码,是整块蒸发。页面能打开,标题和正文都在,唯独代码示例全都不见了。

我第一反应是源文件的问题。但本地一切正常:hugo server 起起来,代码块好好的。于是「本地能跑」成了最误导人的线索。

复现:同一份源,两种产物

这个站点是外部 CI(ESA)构建的,它钉死的 Hugo 版本是 0.146.0;我本机是 0.165。同一份 markdown,两个渲染器给出了完全不同的东西:

1
2
3
4
5
6
7
<!-- 本地 0.165 的产物 -->
<pre><code class="language-bash">kubectl get pods</code></pre>

<!-- 线上 0.146.0 的产物 -->
<div class="goat svg-container">
  <svg ...>...</svg>
</div>

线上的渲染器把一个没有语言标记的围栏(开围栏后面什么都不写)当成了 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 为空,才算「缺语言标记」这个缺陷。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import re
from pathlib import Path

FENCE_RE = re.compile(r"^\s*(`{3,})\s*(.*)$")

def lint_one(path: Path) -> int:
    """返回该文件里「开围栏缺语言标记」的数量。"""
    missing = 0
    in_fence = False
    for raw in Path(path).read_text(encoding="utf-8").splitlines():
        m = FENCE_RE.match(raw)
        if not m:
            continue
        if in_fence:
            # 收围栏:本来就可以是裸的,永远合法,不计
            in_fence = False
        else:
            info = m.group(2).strip()
            in_fence = True           # 进入开围栏
            if not info:              # 开围栏但 info 为空 = 缺标记
                missing += 1
    return missing

if __name__ == "__main__":
    import sys
    total = sum(lint_one(Path(a)) for a in sys.argv[1:])
    print(f"缺标记={total}")

现在对整个仓库跑一遍,输出是 篇=238 / 开围栏=1487 / 缺标记=0——站点长到 200 多篇,这道护栏依然兜得住。

修法

两件事:

  1. 给裸围栏补语言标记。 bash / python / json / yaml / text / toml,块里实际是什么就标什么。commit 292cb2f 把三篇大户清掉了(77 行改动)。
  2. 钉死构建版本。 教训不是「补一次标记」,而是「用和线上一样的二进制构建」。如果 CI 用的是和本地对齐的 0.165,我本机和生产的分叉在 push 之前就能看见。

一个好写法的例子:

1
echo hello   # 围栏头部带语言标记,正常渲染

坏写法就是把这个 bash 去掉,开围栏后面什么都不写——也就是「裸围栏」。线上 0.146 拿到这种块直接走 GoAT,代码就没了。本文为了不让自己触发这个 bug,下面所有示例围栏都带了语言标记;事故里那些坏块是连标记都没有的。

注意收围栏那一行本来就是裸的,这完全正确,也正是为什么你绝不能去数裸行。

三条能带走的

  1. 本地能跑不是上线证据。 构建 / 渲染版本必须和线上一致;CI 要用部署同款二进制,否则「本地绿」只是另一种静默失败。
  2. 空 info string 是缺陷,不是风格。 它决定渲染走哪条路径,不同版本会解释成不同东西。围栏没有语言标记,就该当 bug 修。
  3. 护栏按语义写,别按形状写。 「开围栏缺语言」才是真缺陷;数裸行会把合法收围栏全误报。护栏本身也要在同一个渲染版本下跑,否则它也会给你假绿。

这其实是可观测性的老道理换了个壳:最贵的失败,是看不见的那一种。这次「看不见」,是因为本地和线上的渲染器悄悄分了叉,而分叉本身不在我本地的任何日志里留信号——代码块是到了读者屏幕上才「消失」的。