编译排错：读日志与十大常见错误

LaTeX 的报错方式很特别：它不会弹窗告诉你「第 42 行少了个花括号」，而是甩出一大段带行号的日志，然后在某个位置戛然而止。学会读日志，是从「复制报错信息到搜索引擎」进化到「自己定位问题」的关键一步。本文先建立读日志的方法论，再列出十条最高频的错误，每条都给出「日志长什么样、源头在哪、怎么修」的完整链条，最后提供一份可与知识库联动的排错记录模板。

一、日志结构：先看哪里再看哪里

一次编译产生的日志文件可能上千行，但没有必要从头读。它的结构是有规律的：开头是引擎与格式版本信息，中间是宏包逐个加载的记录，然后是正文处理过程，错误信息散布其中，结尾是资源统计。熟悉结构后，你可以直接跳到关心的区域。

排错时遵循固定顺序：先翻到日志中错误标记处，读它紧跟的行号——那是源文件中的出错位置；再看错误信息给出的上下文，通常是出错点附近的源码片段；最后若报错提到宏包名，优先怀疑最近新加载的宏包冲突。警告不会打断编译，但行内容溢出之类的提示直接关系排版质量，建议每次扫一眼。初学者最常见的错误读法是从头逐行读日志，读到一半就迷失了——记住日志是索引不是小说，跳着读才是正确姿势。

理解日志还有一层收益：你会逐渐分清「错误」与「警告」的差别。错误必须立刻处理，编译在此中断；警告则只是提醒，PDF 照常生成。新手常把警告当灾难，吓得不敢继续；又有人把错误当警告忽略，结果交出去的 PDF 缺章节。养成区分二者的习惯，排错心态会稳很多。

日志的开头与结尾也值得扫一眼：开头写着引擎与格式版本，若别人用你的源码报错，先核对这个版本号是否一致；结尾的资源统计能告诉你这份文档用了多少字体与写入多少页面，某些缺字体问题会在结尾留痕。

二、十大高频错误与修复链条

下面十条覆盖了初学者八成以上的报错来源，按出现频率粗略排序。遇到问题照着对照即可，不必从头通读。每条的修法都遵循同一个模式：先看日志关键词，再看源码对应行，最后动刀子。模式比清单更重要，清单会遗忘，模式会长在手上。

前五条是「编译不过」类，后五条是「能编译但结果不对」类。养成每次保存后编译、每次报错先读日志最后三行的习惯，比死记命令更有效。这十条之外的问题，多与特定宏包相关，此时应直接查该宏包的官方文档而非通用教程——通用教程常滞后于宏包版本。

针对前三条再给一个通用自救法：当报错指向某一行而你看不出问题时，逐段注释掉附近的代码块再编译，错误消失时被注释的部分就是根源。这种「二分定位法」在长文档里尤其有效，比瞪着源码干想快十倍。注释时记得一次只注释一段，否则错误消失你也不知道是哪段造成的。

三、实战：修复一个真实连环错

假设你写公式时把分式命令的两个参数误写成了圆括号形式，日志会立刻报错吗？不一定。引擎会先把括号当作普通字符处理，然后报出「缺少数学模式」或括号不配对这类「看起来在别处」的错误。这说明日志报错位置未必指向真正的根源，而指向「引擎状态错乱的位置」。读懂这一层，你就跨过了排错的第一道门槛。

\documentclass{ctexart}
\begin{document}
错误的写法：\frac(1)(2)。
正确的写法：$\frac{1}{2}$。
\end{document}

修复连环错的经验法则是：从第一个错误开始修，修一个编译一次，不要攒着一起改。因为后续错误很可能是第一个错误的连锁反应——一个未闭合的环境会让后面几十行全部标红，从头修掉一处，后面的报错往往瞬间消失一大片。同理，看到几十条报错不要慌，它们很可能共享同一个根源。

再补一个真实场景：你在表格里少写一个 &，报错可能不是「表格列数不对」，而是几百行之后的「环境未结束」。因为引擎在表格里逐行扫描，失衡的状态要等遇到下一个结构检查点才暴露。知道这一点后你就明白为什么表格报错总在「看起来很远」的地方——先把表格逐行注释定位，再核对每行的列数与分隔符。浮动体与环境未闭合是两大「远程报错」来源，看到位置离谱的报错先怀疑这两类。

四、间发问题：未定义引用与遍数

新手最容易误以为「模板坏了」的场景：辛辛苦苦写完，PDF 里目录页码、图号引用全是问号。这几乎从不是模板问题，而是编译遍数不够。判断方法：看日志里有没有未定义引用的警告——有就说明需要再跑主编译（若含文献则按四遍顺序）。用自动编译工具则全自动处理。这也是「间发问题」的典型：平时没事，一旦大改就出现，原因纯粹是编译流程没跑完而已，与源码质量无关。

这类问题的共同点是「源码本身没问题」，纯粹是编译流程没跑完。遇到问号先跑编译，问号还不消失再去查键名拼写——这个顺序能帮你省下大量怀疑源码的时间。

五、排错工具箱与求助礼仪

几个实用工具能加速定位：自动编译工具会循环编译并打印简明日志；编辑器的正反向跳转能直接从 PDF 定位到出错源码行；查命令归属的命令行工具可以告诉你某个命令由哪个宏包提供。另外，把每次遇到的错误与修法记进自己的知识库，几个月后你会发现自己极少再为同样的问题搜索。知识库结构见本站Obsidian 指南。

一个值得坚持的小动作：每修好一个疑难报错，花三十秒在知识库里记一行「现象—根因—修法」。这个习惯的回报率惊人——同一类报错在不同项目里会反复出现，你的记录比任何搜索引擎都贴合自己的代码风格。

向论坛或群友求助时，请给出三样东西：完整的最小复现源码（只保留触发报错的十几行）、日志报错段、引擎与发行版版本。贴出全部几百行源码只会让愿意帮你的人变少。从几百行日志里快速抓出所有以错误标记开头的行，用正则一秒钟就能完成，参见本站正则表达式一章的实战示例。若你想先自己排查，AI 辅助写作里也有把日志片段喂给大模型求诊断的安全用法。排错能力的尽头不是记忆力，而是这套「读日志—定位—记录」的可复用流程。把流程固化成本文开头的排错清单，你就拥有了一份随经验增值的资产。

六、一页纸排错流程

把全文压缩成一份可照抄的流程，贴在显示器旁，每次报错按它走一遍：

前五步解决眼前的问题，第六步让未来的自己少走弯路。整套流程跑熟之后，你面对任何报错的第一反应都会是「先看日志」，而不是「先搜索」——这个转变本身就是入门与熟练的分水岭。也是本书把编译排错放在前五章的原因：它决定你后续每一章的学习体验。

延伸阅读

• 论文写作指南
• AI 辅助写作
• 正则表达式
• Obsidian 知识管理