2.3 脚注：正文的幕后注释

2.3 脚注：正文的幕后注释

脚注用 [^标记] 在正文插锚、用 [^标记]: 内容 在任意位置安放注释，渲染后注释归集到文档末尾或章节末尾，正文只留一个可点的上标编号。它是长文、技术文档、学术向写作的清爽之道。

动手：给术语安一个脚注

本文的核心结论依赖响应时间[^rt]的测量口径。

[^rt]: 指从请求发出到收到完整响应的耗时，不含客户端渲染时间。
​

渲染后"响应时间"右上角出现小小的编号 1，注释内容出现在文档底部。标记（rt）只是源码里的名字，渲染时统一编号，所以标记名可以随便起，能帮你在源码里认出它就行——用 [^1]、[^术语拼音]、[^note-3] 都合法。

定义的位置也随意：紧跟段落之后或全部堆到文末都可以，渲染结果一致。我习惯写完一段就把定义放在该段后面，源码里离锚点近，好维护；发布前要集中也可以整体搬动。

脚注的三个典型用途

[^cap]: 这里采用最终一致性，权衡了跨区延迟与可用性。
[^src]: 内部压测平台 2024 年 Q3 报告。
[^cache]: 一级缓存命中时可跳过校验步骤。
​

💡 关键直觉：脚注解决的是"对部分读者重要、对多数读者是噪音"的内容。反过来，对所有读者都重要的信息，放脚注里等于藏起来了——该进正文就进正文。

多段脚注与内部格式

脚注内容里可以用行内语法，多段落需要缩进对齐：

正文引用[^long]。

[^long]: 第一段：先说结论。
    第二段：缩进对齐后仍属同一条脚注。
​

支持度因方言而异，长脚注建议控制在一两段内——真需要长篇展开，说明它是正文素材而不是注。

⚠️ 常见坑：脚注是方言扩展，且各实现编号策略不同（全文档连续编号或每章重排）。锚点 [^x] 与定义 [^x]: 的标记必须逐字一致，中英文标点混用（如定义里误用中文冒号）是最常见的"脚注悬浮不落地"原因。

脚注与替代方案的完整决策链

脚注不是"幕后信息"的唯一去处，把它放进完整的决策链里才好选型。候选有四种：脚注、行内括号、文末附录小节、以及"干脆删掉"。判断从读者比例开始——需要这条信息才能读懂正文的读者占多数，那它就是正文，任何"幕后"处理都是错误；占少数但语境上紧贴某句话，行内括号能一句说完就用括号，说不完才轮到脚注；信息与具体句子无关、只与全篇主题相关（比如完整的数据表、环境配置清单），它属于附录小节，脚注反而是错误归类——附录有标题可导航，脚注没有。

最后一档"删掉"最常被跳过，却往往最正确。写作初稿里大量脚注的实质是作者舍不得删的素材：走过的弯路、查过但没用的资料、过时的对比。这些内容对读者几乎零价值，留着只是作者的安慰剂。一个实用的自检：给每条脚注标注它属于哪类——术语展开、出处、幕后细节，三类都归不进的，删除。团队评审长文时，"脚注清单过一遍"是比通读正文更快的高效环节：脚注里的冗余密度通常远高于正文，五分钟就能砍掉一半。数字脚注（[^1]）在源码里要另配注释说明指向，否则多人协作时没人敢删改——这也是标记名建议用有语义的词而非纯数字的团队理由。

脚注定义的位置策略

定义放哪一列也有讲究。多数人把全部定义堆在文末，这是书籍排版习惯的延续；但技术文档更实用的策略是**"节尾就近"**——定义紧跟所在小节末尾，写作时随手定义、修改时不用滚到全文底部去找。CommonMark 与 GFM 对定义位置都无要求，渲染时统一收集到页脚或节尾（取决于渲染器），源码位置不影响输出编号。唯一要避开的位置是段落中间：定义前后的空行如果处理不当，会把正文段落拦腰斩断成两段。

脚注内容的边界同样值得划清：脚注里不该再嵌脚注。多数解析器不支持嵌套脚注，支持的那几个（如 Pandoc）输出效果也难以辨认；需要多层注释说明信息本身层次太深，应当重构成正文小节或附录。脚注里放链接是常见且合理的组合——来源引用常以"作者、文档名、链接"三件套出现；脚注里放表格则基本必挂，表格是多行结构，而脚注定义在很多实现里被当作行内上下文处理，换行与管道都会失效。安全的内容形态是：一两句纯文本加至多一个链接，超出这个复杂度，就轮到正文出场了。

本节要点回顾

• 锚 [^标记] + 定义 [^标记]: 内容，标记自定义、位置随意、渲染统一编号。
• 适用判据：对少数读者重要的信息才下脚注。
• 定义与锚点标记逐字一致，冒号必须是英文半角。
• 方言差异存在，跨平台长文的脚注要有"编号可能变"的心理预期。

脚注编号与引用风格的一次实操

技术长文里最常见的脚注是"来源与限制条件"，动手写一组规范的学术式脚注：

实测结论：单表写入在 2 万 QPS 后出现毛刺[^qps]。

[^qps]: 压测环境 4C8G，内核 5.15，数据为三次取中位数；
    连接池上限 64，客户端与服务器同机房（RTT < 0.5ms）。
​

注意定义里第二行的缩进：相对标记缩进四个空格，解析器把它当作同一定义的续行，渲染合并进同一条脚注——不缩进的话，多数解析器会把这行当普通段落丢在文末。这条"续行缩进"规则与列表项内多段落的规则一脉相承（见 1.3），Markdown 的块级续行逻辑全靠缩进表达，认出这个共性后，脚注、列表、引用的排错可以共用一套直觉。

写作上再给一条配额纪律：每千字脚注不超过三条。脚注密度的警戒信号是"读者一半时间在页脚与正文之间跳跃"——那说明这些信息不是注释而是正文，搬回来堂堂正正写。脚注的珍贵之处恰在稀缺，满页脚注等于把文档写成了两层都是次要信息的三明治。

脚注与"文末注"的分工

最后区分两种容易混淆的装置：脚注（footnote）与文末小节（endnote 式的"参考文献"标题）。判据是内容的性质：对理解正文某一句话有条件的补充，用脚注，锚点贴在那句话旁；独立成立、可单独阅读的来源列表，用文末小节加列表。混用的典型症状是脚注里塞了完整的参考文献条目（带页码、ISBN），读者在页脚读到了半篇论文；或者反过来，"本节测量条件"这种强依附信息被放到了全文末尾，读者翻两屏才找到。分工立清后，一篇文档通常脚注三五条、文末小节至多一个，两个装置各司其职。