$\LaTeX{}$ 之排除错误和寻求帮助（十）

发表于 2025-03-04 更新于 2025-06-11 分类于 LaTeX ， LaTeX学习笔记本文字数： 3k 阅读时长 ≈ 11 分钟

本文主体内容来自一份 (不太) 简短的 LATEX2ε 介绍。

$\LaTeX{}$ 入门用户总会为两大问题头疼：我写的代码到底哪里出错了？如果想要实现某种用法该怎么办？本章首先总结了常见的 $\LaTeX{}$ 错误及应对办法，然后介绍了查找帮助文档的一些方法，最后简单总结了一些常用的宏包。

$\LaTeX{}$ 错误

当用排版引擎编译 $\LaTeX{}$ 代码时，命令行的窗口（终端）会显示大量信息（TeXworks 等编辑器会有一个区域显示这些信息）。当编译过程中出现错误时，信息将会停止在出错的地方，等待我们接下来的操作。

比如说我们有一个明显出错的例子：

\documentclass{article}
\begin{document}
Test \LaTEx{} and it's friends.
\end{document}

编译过程中遇到这个错误将会停顿下来，提示错误，并等待用户输入指令：

1
2
3

! Undefined control sequence.
l.3 Test \LaTEx
             {} and it's friends.

这种错误信息分两部分，前一部分提示了错误的信息，后一部分指出了错误发生的行号，以及通过错落的文字告知发生错误的命令所在位置。如上错误显示 \LaTEx 位置发生了错误，错误信息是“未定义的控制序列”，意思是 \LaTEx 是 $\TeX{}$ 编译器无法识别的一个命令，很显然是把 \LaTeX 的大小写写错了。

处理方式

出现错误时，编译过程将暂停，等待用户输入命令。用户可以直接敲回车跳过当前的错误，继续编译，相当于丢掉了写错的命令，将“Test and it’s friends.”排版出来。但这个例子过于简单，有些复杂的代码中，有可能会由于一个小问题导致一连串的错误。此时可以选择按 $\textbf{S/R/Q}$ 选择跳过接下来的所有错误，或者按 $\textbf{X}$ 直接退出编译，将源代码中的错误修改后重新编译。

常见的 $\LaTeX{}$ 错误信息

在此总结一些经常发生、问题比较明确的 $\LaTeX{}$ 错误：

! Undefined control sequences.

使用了未定义的命令。拼写错误是原因之一（标点符号中英文不匹配）。也有可能是没有调用某个宏包，但用了该宏包定义的命令。
! LaTeX error: Environment … undefined.

使用了未定义的环境。
! Missing $ inserted.

缺少数学环境的符号 $\texttt\$$。多由于将数学符号用在公式之外而导致。
Runaway argument?

! Paragraph ended before … was complete.
! File ended while scanning definition/use of …

这两个错误主要是由于漏写了包裹命令参数的花括号，导致识别参数时出现错误。许多编辑器的括号配对功能有助于检查和消除这类错误。

这类错误还有可能是由于前一次编译中断导致 $\texttt{.aux}$ 等辅助文件不完整，再次编译读入不完整的文件产生错误。解决办法是删除辅助文件并重新编译。
! Extra alignment tab has been changed to .
! Misplaced .

两个错误信息都与表格有关。
- 前者的字面意义是“一行中使用的列分隔符 $\texttt\&$ 太多”，有时可能确实是 $\texttt\&$ 的个数和列格式不匹配，但多数情况是漏掉了行尾的 \\ 命令。
- 后者常出现于漏掉了行尾的 \\ 命令而接着使用 \hline 命令画横线的时候。
! LaTeX Error: Lonely \item – perhaps a missing list environment.
! LaTeX Error: Something’s wrong–perhaps a missing \item.

两个错误信息都与列表环境和 \item 命令有关。前者意味着在没有使用列表环境的情况下用了 \item；后者则相反，是在列表环境中漏了 \item。
! I can’t find file `…’.
! LaTeX Error: File `…’ not found.

两个错误都意味着缺少文件。
- 如果使用 \input 或者 \include 命令添加文件，出现上述错误的原因当然是文件不存在或者文件名不对；
- 如果错误提示里的文件名带 $\texttt{.sty}$ 或者 $\texttt{.cls}$ 扩展名，那么很显然，是因为 没有安装所需的宏包或文档类。
! LaTeX Error: Missing \begin{document}.

字面上是缺少 \begin{document}，实际上往往是由于在 \begin{document} 之前（导言区）输入了文字或某些命令。
! LaTeX Error: Can be used only in preamble.

与上一条相反，由于将必须用于导言区的命令在 \begin{document} 之后使用而产生。
! LaTeX Error: begin{…} on input line ended by \end{…}.

环境首尾不匹配。比如 \begin{enumerate} 用了 \end{itemize} 结尾。或者也可能是由于漏写了 \begin 或者 \end 命令。
! LaTeX Error: Option clash for package `…’.

以 不同选项 重复调用宏包造成冲突。有可能是因为其它宏包内部事先调用了这个宏包，用户再次带选项调用而导致冲突。解决问题的办法是去掉重复调用的宏包。如果宏包允许的话，尽量使用其定义的命令改变设置，减少宏包选项的使用。
! LaTeX Error: Command … already defined,

or name \end… illegal …

使用 \newcommand 或 \newenvironment 定义已有的命令/环境时产生的错误。如果自己确实作了定义，可考虑用 \renewcommand 或 \renewenvironment 定义；如果是宏包定义的命令产生了这个错误，则属于隐性的宏包冲突。

相比之前的“Option clash”，隐性宏包冲突是更难以解决的问题，对各种宏包不熟悉的用户，尤其是使用模板的用户而言，往往难以下手。用户可尝试查找引起冲突的宏包的帮助文档。详尽的手册里通常会告知用户这个宏包应当在某个宏包的前面/后面调用，或者不能与某个宏包一起调用。如果是模板调用了大量宏包导致冲突，可联系模板的作者解决。
! LaTeX Error: Unknown option `…' for package `…’.

调用宏包时指定了不能被其识别的选项。此时应该查找宏包的帮助文档来解决问题。
! Package `…’ error: …

宏包或文档类自定义的错误，由于不正确地使用宏包里的命令而导致。此时应该查找宏包的帮助文档来解决问题。

查找帮助文档

无论是 $\textrm{TeX Live}$ 还是 $\textrm{MiKTeX}$，都提供了一个命令行模式的程序 $\texttt{texdoc}$。比如对 fancyhdr 宏包感兴趣，这时在 Windows 命令提示符或者 Linux 终端输入以下命令，则会弹出宏包的帮助文档 $\texttt{fancyhdr.pdf}$：

1	texdoc fancyhdr

除了宏包的帮助文档外，$\TeX{}$ 发行版还包括了各类有用的文档，有一部分在参考文献中给出。

对于初学者，有一个现实而棘手的问题：某个命令到底是 $\LaTeX{}$ 自有的，还是哪个宏包提供的？ 很遗憾地说，除了通过慢慢积累、熟悉较多宏包之外，没有很方便的办法解决这个问题，因为 $\LaTeX{}$ 的宏包实在太丰富了。

解决这个问题有几点可行的办法：

查询一些综述性的资料，如总结所有 $\LaTeX{}$ 自带命令的文档 ¹、、$\LaTeX{}$ 符号大全 ² 等；
在互联网上搜索自己不清楚的命令；
在论坛上提问求助有经验的人。

常用宏包简介

文字、公式和符号

宏包	简介
$\texttt{amsmath}$	AMS 数学公式扩展。
$\texttt{mathtools}$	数学公式扩展宏包，提供了公式编号定制和更多的符号、矩阵等。
$\texttt{amsfonts}$	AMS 扩展符号的基础字体支持。
$\texttt{amssymb}$	在 $\texttt{amsfonts}$ 基础上将 AMS 扩展符号定义成命令。
$\texttt{bm}$	提供将数学符号加粗的命令 `\bm`。
$\texttt{unicode-math}$	使用 Unicode 数学字体。
$\texttt{nicematrix}$	排版复杂矩阵。
$\texttt{siunitx}$	以国际单位规范排版物理量的单位。
$\texttt{mhchem}$	排版化学式和方程式。
$\texttt{tipa}$	排版国际音标。

排版元素

宏包	简介
$\texttt{ulem}$	提供排版可断行下划线的命令 `\uline` 以及其它装饰文字的命令。
$\texttt{endnote}$	排版尾注。
$\texttt{marginnote}$	改善的边注排版功能。
$\texttt{multicol}$	提供将内容自由分栏的 $\texttt{multicols}$ 环境。
$\texttt{multitoc}$	生成多栏排版的目录。
$\texttt{minitoc}$	为章节生成独立的小目录。
$\texttt{glossaries}$	生成词汇表。
$\texttt{verbatim}$	对原始的 $\texttt{verbatim}$ 环境的改善。提供了命令 `\verbatiminput` 调用源文件。
$\texttt{fancyvrb}$	提供了代码排版环境 $\texttt{Verbatim}$ 以及对版式的自定义。
$\texttt{listings}$	提供了排版关键字高亮的代码环境 $\texttt{lstlisting}$ 以及对版式的自定义。类似宏包有 $\texttt{minted}$ 等。
$\texttt{algorithmic}$	一个简单的实现算法排版的宏包。如果要生成浮动体的话，需要搭配 $\texttt{algorithm}$ 宏包使用。
$\texttt{algorithm2e}$	较为复杂的、可定制的算法排版宏包。类似宏包有 $\texttt{algorithmicx}$ 等。
$\texttt{amsthm}$	定制定理环境。类似宏包包括 $\texttt{theorem}$、$\texttt{ntheorem}$、$\texttt{thmtools}$ 等。
$\texttt{mdframed}$	排版可自动断页的带边框文字段落，提供边框样式的定制功能。
$\texttt{tcolorbox}$	以 $\texttt{TikZ}$ 为基础提供排版样式丰富的彩色盒子的功能。

图表和浮动体

宏包	简介
$\texttt{array}$	对表格列格式的扩展。
$\texttt{booktabs}$	排版三线表。
$\texttt{tabularx}$	提供 $\texttt{tabularx}$ 环境排版定宽表格，支持自动计算宽度的 $\texttt{X}$ 列格式。
$\texttt{arydshln}$	支持排版虚线表格线。
$\texttt{colortbl}$	支持修改表格的行、列、单元格的颜色。
$\texttt{multirow}$	支持合并多行单元格。
$\texttt{makecell}$	支持在单元格里排版多行内容（嵌套一个单列的小表格）。
$\texttt{diagbox}$	排版斜线表头。
$\texttt{longtable}$	提供排版跨页长表格的 $\texttt{longtable}$ 环境。
$\texttt{ltxtable}$	为跨页长表格提供 $\texttt{tabularx}$ 的 $\texttt{X}$ 列格式。
$\texttt{tabularray}$	排版复杂表格（基于 $\LaTeX3$ 实现）。
$\texttt{graphicx}$	支持插图。
$\texttt{bmpsize}$	$\texttt{latex} + \texttt{dvipdfmx}$ 命令下支持 BMP/JPG/PNG 等格式的位图。
$\texttt{epstopdf}$	$\texttt{pdflatex}$ 命令下支持 EPS 格式的矢量图。
$\texttt{wrapfig}$	支持简单的文字在图片周围的绕排。
$\texttt{caption}$	控制浮动体标题的格式。类似宏包有 $\texttt{keyfloat}$ 等。
$\texttt{subcaption}$	提供子图表和子标题的排版。类似宏包有 $\texttt{subfigure}$ 和 $\texttt{subfig}$ 等。
$\texttt{bicaption}$	生成双语浮动体标题。
$\texttt{float}$	为浮动体提供不浮动的 $\texttt{H}$ 模式；提供自定义浮动体结构的功能。

修改版式

宏包	简介
$\texttt{geometry}$	修改页面尺寸、页边距、页眉页脚等参数。
$\texttt{fancyhdr}$	修改页眉页脚格式，令页眉页脚可以左对齐、居中、右对齐。
$\texttt{titlesec}$	修改章节标题 `\chapter`、`\section` 等的格式。
$\texttt{titletoc}$	修改目录中各条目的格式。类似宏包有 $\texttt{tocloft}$ 等。
$\texttt{tocbibind}$	支持将目录、参考文献、索引本身写入目录项。
$\texttt{footmisc}$	修改脚注 `\footnote` 的格式。
$\texttt{indentfirst}$	令章节标题后的第一段首行缩进。
$\texttt{enumerate}$	提供简单的自定义标签格式的 $\texttt{enumerate}$ 环境。
$\texttt{enumitem}$	修改列表环境 $\texttt{enumerate}$ 和 $\texttt{itemize}$ 等的格式。
$\texttt{lettrine}$	生成段落首字母大写的效果。

参考文献

[1] Partl H, Hyna I, Schlegl E. 一份 (不太) 简短的 LATEX2ε 介绍[J]. 2024. https://github.com/CTeX-org/lshort-zh-cn

Karl Berry, Jim Hefferon, Vincent Belaiche. LaTeXe: An unofficial reference manual. (texdoc latex2e)↩︎
Scott Pakin. The Comprehensive LaTeX Symbol List}. (texdoc symbols-a4)↩︎

宏包	简介
\(\texttt{ulem}\)	提供排版可断行下划线的命令 `\uline` 以及其它装饰文字的命令。
\(\texttt{endnote}\)	排版尾注。
\(\texttt{marginnote}\)	改善的边注排版功能。
\(\texttt{multicol}\)	提供将内容自由分栏的 \(\texttt{multicols}\) 环境。
\(\texttt{multitoc}\)	生成多栏排版的目录。
\(\texttt{minitoc}\)	为章节生成独立的小目录。
\(\texttt{glossaries}\)	生成词汇表。
\(\texttt{verbatim}\)	对原始的 \(\texttt{verbatim}\) 环境的改善。提供了命令 `\verbatiminput` 调用源文件。
\(\texttt{fancyvrb}\)	提供了代码排版环境 \(\texttt{Verbatim}\) 以及对版式的自定义。
\(\texttt{listings}\)	提供了排版关键字高亮的代码环境 \(\texttt{lstlisting}\) 以及对版式的自定义。类似宏包有 \(\texttt{minted}\) 等。
\(\texttt{algorithmic}\)	一个简单的实现算法排版的宏包。如果要生成浮动体的话，需要搭配 \(\texttt{algorithm}\) 宏包使用。
\(\texttt{algorithm2e}\)	较为复杂的、可定制的算法排版宏包。类似宏包有 \(\texttt{algorithmicx}\) 等。
\(\texttt{amsthm}\)	定制定理环境。类似宏包包括 \(\texttt{theorem}\)、\(\texttt{ntheorem}\)、\(\texttt{thmtools}\) 等。
\(\texttt{mdframed}\)	排版可自动断页的带边框文字段落，提供边框样式的定制功能。
\(\texttt{tcolorbox}\)	以 \(\texttt{TikZ}\) 为基础提供排版样式丰富的彩色盒子的功能。

宏包	简介
\(\texttt{array}\)	对表格列格式的扩展。
\(\texttt{booktabs}\)	排版三线表。
\(\texttt{tabularx}\)	提供 \(\texttt{tabularx}\) 环境排版定宽表格，支持自动计算宽度的 \(\texttt{X}\) 列格式。
\(\texttt{arydshln}\)	支持排版虚线表格线。
\(\texttt{colortbl}\)	支持修改表格的行、列、单元格的颜色。
\(\texttt{multirow}\)	支持合并多行单元格。
\(\texttt{makecell}\)	支持在单元格里排版多行内容（嵌套一个单列的小表格）。
\(\texttt{diagbox}\)	排版斜线表头。
\(\texttt{longtable}\)	提供排版跨页长表格的 \(\texttt{longtable}\) 环境。
\(\texttt{ltxtable}\)	为跨页长表格提供 \(\texttt{tabularx}\) 的 \(\texttt{X}\) 列格式。
\(\texttt{tabularray}\)	排版复杂表格（基于 \(\LaTeX3\) 实现）。
\(\texttt{graphicx}\)	支持插图。
\(\texttt{bmpsize}\)	\(\texttt{latex} + \texttt{dvipdfmx}\) 命令下支持 BMP/JPG/PNG 等格式的位图。
\(\texttt{epstopdf}\)	\(\texttt{pdflatex}\) 命令下支持 EPS 格式的矢量图。
\(\texttt{wrapfig}\)	支持简单的文字在图片周围的绕排。
\(\texttt{caption}\)	控制浮动体标题的格式。类似宏包有 \(\texttt{keyfloat}\) 等。
\(\texttt{subcaption}\)	提供子图表和子标题的排版。类似宏包有 \(\texttt{subfigure}\) 和 \(\texttt{subfig}\) 等。
\(\texttt{bicaption}\)	生成双语浮动体标题。
\(\texttt{float}\)	为浮动体提供不浮动的 \(\texttt{H}\) 模式；提供自定义浮动体结构的功能。

宏包	简介
\(\texttt{geometry}\)	修改页面尺寸、页边距、页眉页脚等参数。
\(\texttt{fancyhdr}\)	修改页眉页脚格式，令页眉页脚可以左对齐、居中、右对齐。
\(\texttt{titlesec}\)	修改章节标题 `\chapter`、`\section` 等的格式。
\(\texttt{titletoc}\)	修改目录中各条目的格式。类似宏包有 \(\texttt{tocloft}\) 等。
\(\texttt{tocbibind}\)	支持将目录、参考文献、索引本身写入目录项。
\(\texttt{footmisc}\)	修改脚注 `\footnote` 的格式。
\(\texttt{indentfirst}\)	令章节标题后的第一段首行缩进。
\(\texttt{enumerate}\)	提供简单的自定义标签格式的 \(\texttt{enumerate}\) 环境。
\(\texttt{enumitem}\)	修改列表环境 \(\texttt{enumerate}\) 和 \(\texttt{itemize}\) 等的格式。
\(\texttt{lettrine}\)	生成段落首字母大写的效果。