B. 排除错误、寻求帮助

B. 排除错误、寻求帮助 #

B.1 LaTeX 错误 #

先找日志中的第一条错误，修好后再编译。一个缺失的花括号可能引发几十条后续错误，最后一条不一定最接近原因。

例如，把 \LaTeX 写成 \LaTEx 后，日志可能显示：

! Undefined control sequence.
l.3 Test \LaTEx
              {}

l.3 表示第 3 行附近，错落显示的文字帮助定位命令。LaTeX 区分大小写；遇到不认识的命令也可能是漏了宏包，而不仅仅是拼写错误。

常见错误 #

错误信息 优先检查
Undefined control sequence 命令拼写、大小写、所属宏包。
Environment ... undefined 环境名和宏包依赖。
Missing $ inserted 数学符号是否放在数学模式里；正文下划线是否应写成 \_。
Runaway argument?、File ended while scanning... 是否少了右花括号、环境结束或其他终止符。
Extra alignment tab... 单元格数是否超过列数，上一行是否少了 \\。
Misplaced \noalign \hline 前是否已经结束上一行。
Lonely \item、perhaps a missing \item 列表环境与 \item 是否对应。
File ... not found 文件是否存在，路径、大小写是否匹配；缺少 .sty/.cls 时检查依赖。
Missing \begin{document} 正文是否误放进导言区，也可能真的漏了正文开始。
Can be used only in preamble \usepackage 等是否误放进正文。
\begin{...} ... ended by \end{...} 环境名或嵌套顺序是否配对。
Option clash for package... 同一宏包是否带不同选项重复加载，包括模板间接加载。
Command ... already defined 自定义命令是否与已有命令或宏包冲突。
Unknown option... 选项是否拼错，是否属于该宏包和当前版本。
font cannot be found 字体是否在编译环境中，名称或文件名是否正确。

交互式本地编译出错后可以退出修改，没必要一路按回车忽略错误。在线环境可能继续运行并输出不完整 PDF，生成了 PDF 不等于没有错误。

警告也要看 #

  • Overfull \hbox：内容伸出行宽，检查长单词、URL、公式、表格或不换行的盒子。
  • Underfull \hbox / Underfull \vbox：某处过于松散，结合 PDF 判断，不一定需要修复。
  • Missing character：当前字体没有该字形，编译成功也可能缺字。
  • Reference ... undefined / Citation ... undefined：检查标签、引用键以及是否完成所需的编译流程。
  • 要求重跑 LaTeX、BibTeX 或 Biber：按所用工作流处理，不能把这些程序当作同义词。

若错误来自上次中断留下的辅助文件，可在备份后使用项目的“清理辅助文件”功能再编译。不要误删 .tex、.bib、图片和自定义样式。

制作最小工作示例 #

求助前，复制项目并逐步删去无关内容，保留仍能触发错误的最短示例。它应该包含：

  1. 文档类和必要宏包。
  2. 触发问题的几行内容。
  3. 编译器名称与第一条错误信息。
  4. 必要的最小附属文件；不包含私人资料或密钥。

每删一部分就重新编译。只发一张模糊的报错截图，往往不足以判断缺少哪个宏包或哪一对括号。

B.2 查找帮助文档 #

本地发行版提供 texdoc。例如：

texdoc ctex
texdoc amsmath
texdoc fancyhdr
texdoc pgf

在 TeXPage 等在线环境中，可以到 CTAN 查找宏包页面和文档。手册的版本应尽量与实际编译环境一致。

查命令时同时问三个问题：它属于哪个宏包？该放在导言区还是正文？要求什么编译器或附属程序？确认这些前提往往比反复改命令更有效。

B.3 常用宏包简介 #

以下按用途分类列出查阅入口，不是建议把它们全部加载。功能相似的宏包往往是替代方案。

B.3.1 文字、公式和符号 #

宏包 用途
amsmath、mathtools 数学公式与扩展对齐功能。
amsfonts、amssymb、bm 传统数学字体、符号与加粗。
unicode-math OpenType 数学字体，使用现代引擎。
nicematrix 复杂矩阵。
siunitx 数值、单位及数字列。
mhchem 化学式和反应式。
tipa 国际音标。

B.3.2 排版元素 #

宏包 用途
ulem 可断行下划线等文字装饰。
endnotes、marginnote 尾注、边注。
multicol、multitoc、minitoc 正文分栏、多栏目录、局部目录。
glossaries 术语表。
verbatim、fancyvrb、listings 原样代码、可定制代码、语法高亮。
algorithmic 配合 algorithm 算法内容与算法浮动体。
algorithm2e、algorithmicx 其他算法排版方案。
amsthm、ntheorem、thmtools 定理与证明。
mdframed、tcolorbox 带框或彩色内容块。

B.3.3 图表和浮动体 #

宏包 用途
array、tabularx 列格式与定宽表格。
booktabs、arydshln、colortbl 三线表、虚线表格线、表格颜色。
multirow、makecell、diagbox 跨行单元格、单元格内换行、斜线表头。
longtable、ltxtable、tabularray 跨页或复杂表格。
graphicx、wrapfig 插图与文字绕排。
caption、subcaption、bicaption 图表标题、子图表、双语标题。
float 自定义浮动体及固定位置的 H 模式。

bmpsize、epstopdf 等工具服务于特定图片格式和传统编译流程；采用本教程的 XeLaTeX 和常见 PDF/PNG/JPEG 图片时，不必为它们额外配置一套转换流程。

B.3.4 修改版式 #

宏包 用途
geometry、fancyhdr 页面参数、页眉页脚。
titlesec、titletoc、tocloft 标题与目录格式。
tocbibind 将目录、文献等自身加入目录。
footmisc、indentfirst 脚注格式、标题后首段缩进。
enumerate、enumitem 列表标签与间距。
lettrine 段落首字母放大下沉。

已有模板或 ctex 设置相同功能时，先查其接口，避免多个宏包重复接管同一项样式。

← 自定义命令 · 来源与许可 →