LaTeX 的报错信息经过设计，只看 ! 后面的头几个词，就能知道是谁在抱怨。什么前缀都没有的 ! Missing $ inserted. 来自 TeX 引擎本身，! LaTeX Error: 来自 LaTeX 内核，! Package hyperref Error: 来自它点名的那个宏包。学会分辨这一点，第一行就能决定该改的是自己的稿件、导言区的加载顺序，还是别人的缺陷追踪系统。本页是一份索引：把人们真正会遇到的消息按原文列出，说明每一条实际上在讲什么，并指向深入讲解它的页面。这里列出的每条消息都在 TeX Live 2024 上实际复现过。
! 后面的字眼指出发话者：TeX、LaTeX、宏包，还是警告
以 ! 开头的行是错误，可能中止构建；没有 ! 的行是警告或提示，构建照常继续。而错误又分三层，! 紧后面的字眼说明是哪一层。 最底层是 TeX 引擎，它的消息完全没有前缀——! Missing $ inserted. 四十年来一字未改，不加载 LaTeX 的纯 TeX 也会打印一模一样的句子。中间层是 LaTeX 内核的 ! LaTeX Error: …，最上层是宏包和文档类的 ! Package X Error: … 与 ! Class X Error: …。层次越高措辞越友好，层次越低就越接近 TeX 真正卡住的地方。 出现没有前缀的消息，通常意味着稿件本身的语法坏了。
| 行的形态 | 发话者，以及对构建的影响 |
|---|---|
! Missing $ inserted. | TeX 引擎本体；没有前缀就是标志，说明稿件语法坏了 |
! LaTeX Error: ... | LaTeX 内核；违反了 LaTeX 关于环境、引用或导言区的规则 |
! Package X Error: ... | 被点名的宏包 X；用 texdoc X 读它自己的手册通常是最快的下一步 |
! Class X Error: ... | 文档类 X；在期刊类里往往是在通知你违反了排版规定 |
LaTeX Warning: ... | 内核警告；构建照样成功，退出码仍为 0，过期引用就是这样活下来的 |
Package X Warning: ... | 宏包警告；有的会带 on input line N，有的故意不带 |
Overfull \hbox (...) | 直接来自段落排版器；既没有 ! 也没有 Warning 这个词 |
Package X Info: ... | 纯信息；只留在 .log 里，不进终端，但常常能解释后面的失败 |
TeX 引擎的错误：没有前缀的消息
这一组消息是在报告「TeX 无法继续读下去了」，原因几乎无一例外是花括号、$ 或 & 的配对，以及数值的写法。 措辞生硬，是因为它写于 LaTeX 尚不存在的年代。反过来说，这些字符串在任何发行版、任何年代的文档里都完全一致，很适合拿去搜索。下面的文面都在 TeX Live 2024 上实际复现过。
| 消息 | 真正的含义与第一步 |
|---|---|
! Undefined control sequence. | 上一行最右端的命令未定义：拼写错误、忘了加载宏包，或定义写得太晚 |
! Missing $ inserted. | 在正文里用了只属于数学模式的符号；_、^、\alpha 是常见的触发者 |
! Missing } inserted. | { 尚未闭合就有东西结束了；原因在报告位置的上游 |
! Too many }'s. | } 多了一个；多半是前面某行少写了一个 { |
! Extra alignment tab has been changed to \cr. | 表格某行的 & 超过了列格式允许的数量；对照列说明数一数 |
! Misplaced alignment tab character &. | 在表格之外写了 &；要字符本身请写 \& |
! Double subscript. | 同一个原子上有两个 _，如 x_1_2；用花括号合并成 x_{12} |
! Missing number, treated as zero. | 该给长度或个数的地方没有数字；\hspace{} 这样的空参数最典型 |
! Illegal unit of measure (pt inserted). | 数字没带单位，如 \rule{1}{2pt}；补上 cm、pt 或 em |
! Paragraph ended before \x was complete. | 参数中间出现了空行；上方紧接着的 Runaway argument? 就是线索 |
! File ended while scanning use of \x. | 文件读完了参数还没闭合——缺 } 的终末形态 |
! Missing \endcsname inserted. | \csname … \endcsname 中间混进了不可展开的东西；怀疑拼接出来的宏名 |
! TeX capacity exceeded, sorry [...] | 方括号里是耗尽的资源名；[grouping levels=255] 指向失控的递归 |
! Emergency stop. | 在无法交互的场合被索要输入——非交互模式下找不到文件时的常见结局 |
LaTeX 内核的错误：以 ! LaTeX Error: 开头的那些
这一类违反的是 LaTeX 的规矩而不是 TeX 的语法，措辞具体得多，因此改法往往是唯一的。 环境不匹配、\usepackage 放错地方、只能用于导言区的命令、文件不存在——每一条都是 LaTeX 自己定下的规则。另外，.log 里每条这样的消息后面都跟着一段帮助文字，比终端上那一行说得更具体，看不明白时请打开日志。
| 消息 | 真正的含义与第一步 |
|---|---|
! LaTeX Error: File `x.sty' not found. | 宏包未安装或拼错；用 kpsewhich x.sty 确认，用 tlmgr install x 安装 |
! LaTeX Error: Environment x undefined. | 定义该环境的宏包没有加载；顺便也检查一下环境名的拼写 |
! LaTeX Error: \begin{x} on input line N ended by \end{y}. | 环境是交叉而不是嵌套；N 是打开的那一行，从那里往下看 |
! LaTeX Error: Command \x already defined. | 对已存在的名字用了 \newcommand；确实想覆盖就改用 \renewcommand |
! LaTeX Error: Missing \begin{document}. | 导言区里出现了可打印的东西；一个非空白字符就足以引发 |
! LaTeX Error: Option clash for package x. | 第二次加载索要了第一次没有的选项；用 \PassOptionsToPackage 解决 |
! LaTeX Error: Something's wrong--perhaps a missing \item. | 列表是空的，或者在第一个 \item 之前有正文 |
! LaTeX Error: There's no line here to end. | 在还没有行的位置写了 \\，常见于段首或 center 的开头 |
! LaTeX Error: Not in outer par mode. | 把浮动体放进了另一个浮动体或盒子里；figure 不能放在 figure 或 minipage 中 |
! LaTeX Error: \caption outside float. | \caption 出现在 figure 或 table 之外；把它包进去，或改用 \captionof |
! LaTeX Error: Can be used only in preamble. | 在正文里用了 \usepackage 之类只能出现在导言区的命令 |
! LaTeX Error: \usepackage before \documentclass. | 在 \documentclass 之前用了 \usepackage；那个位置只有 \RequirePackage 有效 |
! LaTeX Error: Unknown option `x' for package `y'. | 该宏包从未声明这个选项；检查拼写和宏包版本 |
! LaTeX Error: Unicode character X (U+NNNN) | 该字符没有定义；在 pdfLaTeX 下这涵盖 CJK 和表情符号，而 XeLaTeX、LuaLaTeX 可以接受 |
宏包的错误：! Package X Error: 是 X 在说话
这一层的消息是被点名的宏包自己写的文字，也就是说同样的措辞会出现在该宏包的手册里——打开 texdoc X 搜索这条消息，是最短的路径。 内容也很具体：这个环境不能用在这里、这个颜色没有定义、这个宏包和那个不能共存。处理办法常常就直接写在里面。下面这些都是在 TeX Live 2024 上实际触发出来的。
| 消息 | 真正的含义与第一步 |
|---|---|
! Package biblatex Error: Incompatible package 'natbib'. | biblatex 与 natbib 无法共存；改用 \usepackage[natbib=true]{biblatex} |
! Package cleveref Error: cleveref must be loaded after hyperref!. | 加载顺序的要求：cleveref 要在 hyperref 之后，也要在 varioref 之后 |
! Package amsmath Error: \begin{split} won't work here. | split 不能单独使用；必须放在 equation 或 align 内部 |
! Package xcolor Error: Undefined color `x'. | 颜色名未定义；加载 dvipsnames 之类的色名集，或用 \definecolor 声明 |
! Package babel Error: Unknown option 'x'. | 语言名拼错，或者该语言的文件没有安装 |
! Package pdftex.def Error: File `x.png' not found: using draft setting. | 找不到图片；会排出一个空框并继续运行，请检查路径和扩展名 |
! Package inputenc Error: ... | 在 TeX Live 2024 上几乎见不到：UTF-8 的处理已移入内核，inputenc 基本无事可做 |
警告：不会中止构建，但放着不管就会交出错误的 PDF
警告不会中止构建，也不会把退出码从 0 改掉，于是 CI 会判定为「成功」。这正是它们危险的地方：引用还是 ?? 的 PDF、编号落后一版的 PDF，都是从这里诞生的。 其中两条尤其要紧——LaTeX Warning: There were undefined references. 和 Label(s) may have changed. Rerun to get cross-references right.——它们是「请再编译一次」的指令，不是可以将就的警告。写构建脚本时，要么检测这两行并重跑，要么干脆把这件事交给 latexmk。
| 消息 | 真正的含义与第一步 |
|---|---|
Overfull \hbox (12.3pt too wide) in paragraph at lines 4--5 | 某行超出了版心；括号里的数值就是超出量，不到 1pt 大可不必理会 |
Underfull \hbox (badness 10000) in paragraph at lines 4--5 | 某行被拉得过松；badness 10000 是最差值，滥用 \linebreak 或 \\ 是常见诱因 |
Overfull \vbox (26.3pt too high) detected at line 4 | 溢出发生在纵向：某个盒子塞不进这一页 |
LaTeX Warning: Reference `x' on page 1 undefined on input line 3. | 该标签还不在 .aux 里：要么这是第一次运行，要么 \label 拼错了 |
LaTeX Warning: Citation `x' on page 1 undefined on input line 3. | 还没运行 bibtex 或 biber，或者这个文献键不在 .bib 里 |
LaTeX Warning: Label `x' multiply defined. | 同一个标签存在两处；指向它的 \ref 只能落在其中一个上 |
LaTeX Warning: There were undefined references. | 运行结束时的汇总；带着这行出货，PDF 里就还留着 ?? |
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. | 编号与上一次不一致；再编译一次就会消失 |
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined | 粗体加小型大写这类组合并不存在；会用替代字体，只是外观有变 |
Package hyperref Warning: Token not allowed in a PDF string (Unicode): | 标题里的数学无法进入 PDF 书签；用 \texorpdfstring{数学}{纯文本} 分开写 |
已经不再出现的消息：只活在过时资料里
搜索到的老答案里，仍然引用着 TeX Live 2024 已经不会产生的消息；看不到同样的字符串，并不说明你的环境坏了。 最典型的是 Unicode 字符错误。它过去写作 ! Package inputenc Error: Unicode character …；如今 UTF-8 的处理已在内核里，于是变成 ! LaTeX Error: Unicode character 日 (U+65E5)，下一行接 not set up for use with LaTeX.。而且 → 和 € 已经完全不再报错——实测下来，字符分成 pdfLaTeX 现在接受的和依然拒绝的两类，后者包括 CJK、表情符号和 ≤。xcolor 的选项冲突也出于同样的原因成了历史（详见「宏包冲突」一页）。
- Unicode 字符 — 现在的消息是
! LaTeX Error: Unicode character 日 (U+65E5)，而不是! Package inputenc Error:。在 pdfLaTeX 下→和€能过，CJK、表情符号和≤仍然不能。 xcolor的选项冲突 —\usepackage[dvipsnames]{xcolor}之后再写\usepackage[table]{xcolor}完全不报错，因为 xcolor 已改用键值式选项。caption与subfigure— 过去那条「不能与之合作」的错误已经消失，如今.log里只留下Package caption Info: subfigure package is loaded.subfigure与subcaption— 同时加载不会报错。取而代之的是\begin{subfigure}被老的\subfigure命令吞掉，冒出! Missing number, treated as zero.这类看似无关的错误。