LaTeX 的报错信息看起来晦涩，但格式很固定：以 ! 开头的一行是错误本身，下面以 l. 加数字开头的一行告诉你出错的行号，并把这一行在出错位置断开显示。学会看这两行，大部分问题几分钟就能定位。本文按出现频率列出最常见的报错，每条都给出日志原文、原因和改法。错误写法只作为代码展示，可以直接打开的示例都是改好的版本。

先学会读日志

以拼错命令为例，日志是这样的：

! Undefined control sequence.
l.3 \textbf{a} \tetxbf
                      {b}

• 第一行说明错误类型：有一个没有定义的命令。
• l.3 表示源文件第 3 行；这一行被分成上下两段，上一段的末尾就是出错的位置，这里是 \tetxbf。

处理报错的几条原则：

1. 只看第一个错误。 后面的错误常常是第一个错误引起的连锁反应，改掉第一个再重新编译。
2. 行号指的是 LaTeX 发现问题的位置，真正的原因可能在前面几行，比如一个没有闭合的花括号。
3. 编辑器显示的错误列表来自日志。列表看不明白时，打开完整的 .log 文件，搜索以 ! 开头的行。
4. 出现 Emergency stop 时，LaTeX 已经无法继续，不会生成 PDF；只有 Warning 时 PDF 照常生成，但要看是否影响结果。

Undefined control sequence：命令没有定义

原因有三种：

• 命令拼错了，如 \tetxbf、\beign；
• 命令来自某个宏包，但没有加载它。例如没加载 booktabs 就用 \toprule，没加载 graphicx 就用 \includegraphics，没加载 amsmath 就用 \text；
• 命令只在特定条件下存在。例如 ctex 的 \lishu 只在部分字库里定义，换到 Fandol 字库就成了未定义命令。

改法：看 l. 那一行上一段末尾的命令名。拼写没错时，查这个命令属于哪个宏包，在导言区加上 \usepackage{...}。

Missing $ inserted：数学符号写在了正文里

变量 x_1 与系数 \alpha 成正比。

! Missing $ inserted.
l.3 变量 x_

原因：_、^ 以及 \alpha、\sum、\frac 等数学命令只能在数学模式里使用。LaTeX 在正文里遇到它们，会尝试自动插入 $ 进入数学模式，于是报这个错。另外几种常见情形：

• 文件名、网址里的下划线，如 data_2026.csv，要写成 data\_2026.csv，或用 \verb 或 \url；
• 在 equation、align 等公式环境里留了空行。空行表示分段，公式里不允许，日志会同时出现 Display math should end with $$。

改法：行内公式用 $...$ 或 \(...\)，独立公式用 \[...\] 或 equation。

公式里直接写中文不会报错，但汉字会消失，日志里只有 Missing character 警告；英文单词则会变成斜体。公式中的文字一律写在 \text{} 里。

% !TEX program = xelatex
% title: 修好的数学模式与特殊字符
\documentclass{ctexart}
\usepackage{amsmath} % 提供 \text 和 align 等环境

\begin{document}

\section{数学符号写在数学模式里}
% 错误写法：x_1 和 \alpha 直接写在正文里 → Missing $ inserted
% 正确写法：行内公式用 $...$ 或 \(...\)
变量 $x_1$ 与系数 \(\alpha\) 成正比。

% 独立公式用 \[...\] 或 equation，不要用 $$...$$
\[
  E = mc^2
\]

% 公式里的中文或单词用 \text{}，否则字母会变成斜体变量、中文会消失（日志里只有 Missing character 警告）
\begin{equation}
  v_{\text{平均}} = \frac{s}{t} \quad \text{其中 } t > 0
  \label{eq:speed}
\end{equation}
由式~\eqref{eq:speed} 可以算出平均速度。

\section{正文里的特殊字符要转义}
% 这十个字符在 LaTeX 里有特殊含义：# $ % & ~ _ ^ \ { }
% 在正文中原样输出时要加反斜杠或用专门的命令
文件名 data\_2026.csv，增长 50\%，A \& B，编号 \#1，
价格 \$5，花括号 \{ \}，
波浪号 \textasciitilde，脱字符 \textasciicircum，反斜杠 \textbackslash。

% 路径或网址里有很多下划线时，用 \verb 或 url 宏包的 \url
路径 \verb|C:\my_files\report_v2.tex|。

\end{document}

特殊字符引起的报错

LaTeX 有十个特殊字符：# $ % & ~ _ ^ \ { }。直接写在正文里会出各种错误：

% 最隐蔽：它是注释符，后面整行都会被忽略，不报错，只有读 PDF 时才发现少了字。

File not found：文件找不到

! LaTeX Error: File `notapkg.sty' not found.

• .sty 或 .cls 找不到：宏包名或文档类名拼错，或者当前 TeX 发行版里没有这个宏包。学校模板自带的 .cls、.sty 文件要和主文件放在同一个目录。
• 图片找不到：pdfLaTeX 报 File `figs/plot.png' not found；XeLaTeX 先给出同样内容的警告，再报 Unable to load picture or PDF file 'figs/plot.png'。检查文件是否上传、路径是否相对于主文件、大小写是否完全一致。在线编译运行在 Linux 上，Plot.png 和 plot.png 是两个文件。详见插图与浮动体。
• \input、\include 的文件找不到：同样是路径和大小写的问题。

Option clash：宏包选项冲突

\usepackage{hyperref}
\usepackage[colorlinks]{hyperref}

! LaTeX Error: Option clash for package hyperref.

原因：同一个宏包被加载了两次，第二次带了不同的选项。LaTeX 中一个宏包只会真正加载一次，后来的选项无法再生效，于是报错。最常见的情形是模板（或模板加载的其他宏包）已经加载了 hyperref、xcolor、graphicx，你又带着选项加载了一遍。

改法有两种：

1. 宏包有设置命令的，加载之后用设置命令改选项。hyperref 用 \hypersetup{colorlinks=true}，caption 用 \captionsetup{...}。
2. 没有设置命令的，在 \documentclass 之前写 \PassOptionsToPackage{选项}{宏包名}，提前登记选项，不管之后由谁加载这个宏包，都会带上它。

% !TEX program = xelatex
% title: 修好的 Option clash
% 办法一：在 \documentclass 之前用 \PassOptionsToPackage
% 预先登记选项，无论之后谁先加载 xcolor，都会带上这些选项
\PassOptionsToPackage{table}{xcolor}
\documentclass{ctexart}

% 假设下面这行来自模板（模板已经加载了 hyperref）
\usepackage{hyperref}

\usepackage{xcolor}
% 错误写法：再写一次 \usepackage[colorlinks]{hyperref}
%   → LaTeX Error: Option clash for package hyperref.
% 办法二：宏包已经加载过，就用它提供的设置命令改选项
\hypersetup{
  colorlinks = true,
  linkcolor  = blue,
  urlcolor   = teal,
}

\begin{document}

\section{示例}\label{sec:demo}
第~\ref{sec:demo} 节的链接是蓝色的，
网址 \url{https://ctan.org} 是青色的。

% table 选项来自 \PassOptionsToPackage，所以可以用 \rowcolor
\begin{tabular}{lc}
  \rowcolor{gray!20} 项目 & 数值 \\
  甲 & 1 \\
  乙 & 2 \\
\end{tabular}

\end{document}

Missing \begin{document}

! LaTeX Error: Missing \begin{document}.

原因：导言区（\documentclass 和 \begin{document} 之间）出现了会产生输出的内容。常见的有：

• 不小心在导言区写了正文文字，或者粘贴代码时带进了多余的字符；
• \begin{document} 拼错，如 \begin{docment}，这时还会先报 Environment docment undefined；
• 某个宏包或自定义命令的定义里少了花括号，后面的内容被当成了正文。

改法：从 l. 指出的行往上找，删掉导言区里不是命令的内容。

花括号和环境没有配对

Runaway argument?
! File ended while scanning use of \textbf .

这表示 \textbf{ 的花括号一直没有闭合，LaTeX 读到文件末尾也没找到 }。另一种是环境没有结束：

! LaTeX Error: \begin{itemize} on input line 3 ended by \end{document}.

日志已经写明了 \begin{itemize} 在第 3 行，去那里补上 \end{itemize} 即可。

Overfull \hbox：内容超出了页边（警告）

Overfull \hbox (20.86728pt too wide) in paragraph at lines 12--13

这是警告，PDF 照常生成，意思是某一行比版心宽了约 21pt，伸进了右边距。常见原因和改法：

• 长网址：加载 xurl 宏包，网址可以在字母、数字和 /、.、- 等字符处断行；
• 长英文单词或代码：用 \- 标出可以断开的位置，或改写句子；
• 图片、表格写死了宽度：改成 \linewidth 的比例。注意段首缩进也占宽度，宽度等于整行的图片前要加 \noindent，或放进 figure 环境；
• 表格太宽：见表格中关于列宽的部分。

暂时找不到是哪一行时，在文档类选项里加 draft，每个溢出的行尾会出现一个黑色方块，定稿前去掉；注意它同时让图片只显示为带文件名的空框。只想看溢出位置时，可以在导言区写 \setlength{\overfullrule}{5pt}。Underfull \hbox 则表示某一行太松、空白被拉得过大，通常可以忽略。

% !TEX program = xelatex
% title: 修好的 Overfull hbox
\documentclass{ctexart}
\usepackage{xurl}     % 允许网址在字母、数字和 / . : - 等处断行（自动加载 url）
\usepackage{hyperref}
\usepackage{graphicx}

\begin{document}

\section{长网址}
% 没有 xurl 时，这个网址在行尾放不下，日志里报 Overfull \hbox
数据来自 \url{https://example.com/datasets/very-long-directory-name/another-long-subdirectory/file_2026.csv}。

\section{长英文单词}
% 连字符规则不认识的词，用 \- 标出可以断开的位置
The function is called
super\-cali\-fragi\-listic\-expiali\-docious\-Handler in the code.

\section{太宽的图片}
% 宽度写成行宽的比例，不要写死成超过版心的长度。
% 段首缩进也占宽度：直接写 \includegraphics[width=\linewidth]{...}
% 会多出 2 个汉字宽，所以加 \noindent（或放进 figure 环境）
\noindent\includegraphics[width=\linewidth]{example-image}

\section{临时检查}
% draft 选项会在每个溢出的行尾画一个黑块，方便找到位置；
% 定稿前去掉。这里没有打开：\documentclass[draft]{ctexart}
Overfull 是警告，不影响生成 PDF，但说明有内容伸进了页边距。

\end{document}

引用显示为 ?? 或 [?]

LaTeX Warning: Reference `fig:demo' on page 1 undefined on input line 3.
LaTeX Warning: Citation `zhang2002' on page 1 undefined on input line 5.

\ref 和 \cite 需要多次编译：第一次记录标签，第二次才能填入编号；参考文献还要在中间运行 BibTeX 或 biber。多编译一次仍有警告时，检查标签名或文献 key 的拼写，以及 \label 是否写在 \caption 之后。参考文献的设置见 GB/T 7714 参考文献。

中文相关的报错

这几条的详细解释见中文排版与字体。

本文的修正版示例可以在 JointTex 中一键打开为新项目并编译，可以在其中故意改错，对照日志观察每种报错。