> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/latex/zh-cn/zhi-shi-ku/066-how-to-find-and-fix-errors-reported-in-generated-files.md).

# 如何查找并修复生成文件中报告的错误

## 简介

有时 Overleaf 会报告由以下名称的文件引起的错误，例如 `output.toc`, `output.bbl`，等等，但这些文件 *在你的项目中甚至都不存在*。那这些文件是从哪里 *来的* 以及，更重要的是，你要如何 *定位* 和 *修复* 这些错误？

> ![Gen-toc-error.png](/files/77823bb4cd7e7289d845630fbfc80c0542359c3f) “可是我项目里甚至都没有 **报告说 3 版在** 这个 `output.toc` 文件！”

这些“神秘文件”是衍生文件：它们是在 LaTeX 编译过程中生成的辅助文件，但它们也可能触发错误，而这些错误通常源于你项目源文件中的编码问题。本文使用一个 [真实的、充满错误的示例](#playing-detective-locating-errors-in-generated-files) 来展示如何将这类错误追踪到你项目源文件中的原始位置。

## LaTeX 编译过程中生成的文件

除了输出 `.pdf` 文件之外，LaTeX 编译过程还会生成若干文件类型，其中包含标签、交叉引用、页码等信息。一些辅助文件类型并不是由 LaTeX 编译器直接创建的，而是由排版过程中使用的其他处理工具创建的：例如，格式化后的参考文献列表和索引。这些生成的文件必须在后续运行时被编译器读取，这样最终的 `.pdf` 文件才会填充正确的列表、引用和交叉引用。

LaTeX 以及相关处理工具需要写入和读取辅助数据文件，这意味着在总文件数据集收敛（稳定）并生成最终排版好的（稳定的） `.pdf` 文件之前，可能需要多个编译/处理步骤。一个典型的排版循环可能是：

`pdflatex`$$\mapsto$$`bibtex`$$\mapsto$$`pdflatex`$$\mapsto$$`pdflatex`

在本地 LaTeX 安装中，你可能需要自己执行每个中间步骤，或者你也可以使用诸如 [make](https://www.gnu.org/software/make/manual/), [latexmk](https://ctan.org/pkg/latexmk) 或 [arara](https://ctan.org/pkg/arara)之类的构建工具来自动化这一串流程。 [Overleaf 使用 latexmk](/latex/zh-cn/zhi-shi-ku/064-how-does-overleaf-compile-my-project.md)，下面的视频展示了你每次点击 Overleaf 项目中的“Recompile”按钮时会发生什么。

{% embed url="<https://videos.ctfassets.net/nrgyaltdicpt/Uo3I2FXEI8H6aFPBZq171/e2139f9575a4db6955dc2278dc08283c/latexmk-ol.mp4>" %}

通常，生成的文件与正在编译的 `.tex` 文件具有相同的文件名；例如，如果你正在编译 `**main**.tex`，那么生成的文件会被命名为 `**main**.aux`, `**main**.toc`, `**main**.lof` 等等。不过， *在 Overleaf 上* 编译 `\jobname` 始终设置为 `**output**`，因此你 Overleaf 项目中的 [生成文件](/latex/zh-cn/zhi-shi-ku/150-view-generated-files.md) 生成文件始终命名为 `**output**.aux`, `**output**.toc`, `**output**.lof` 等等。这些生成的文件可以从你的 Overleaf 项目中下载，但不能在 Overleaf 中查看或编辑。

## 来自生成文件的编译错误

主项目中的编码错误 `.tex` 文件中的错误可能会被带到生成文件中。例如，一个未转义的 `&` 中 `\section{Introduction & Background}` 会进入生成的 `.toc` 文件。当生成的 `.toc` 文件随后被下一次 `pdflatex` 编译运行读取时，就会报出“来自 .toc 文件”的错误信息。然而，当前的 LaTeX 日志和错误报告并不会把 `.toc` 文件（以及其他生成文件）中的行与其在源 `.tex` 文件中的原始位置关联起来：原始错误应在何处修正，可能并不立刻明显。

下面是另一个 LaTeX 编辑器中错误展示方式的示例：虽然你可以点击错误信息以打开生成的 `.toc` 或 `.aux` 文件中相关的那一行，但并没有一条路径可以从错误跳回到源 `.tex` 文件中的原始位置。即使你通过替换 `&` 配合 `\&` 在 `.toc` 文件中的内容来修正错误，这也并不能真正解决问题：下次你编译 `.tex` 文件时， `.toc` 文件会被重新生成，同样的错误又会被写回 `.toc` 文件中。

![Texstudio-errors-generated-files.gif](/files/2768fd23fe0b774c1a3eb4b1d9a57693265a3ca4)

当错误被报告为来自生成文件时，正确的解决方法是找出源文件中实际的错误来源并加以修正。错误信息通常会包含上下文信息，也就是错误周围的一些文本或代码，因此在源文件中进行文本搜索会有助于定位它们。这些错误本身往往很常见：你可以在 [此帮助页面](/latex/zh-cn/latex-ji-chu/05-errors.md)，或者在 [TeX FAQ 列表](https://texfaq.org/#errors).

## 首先，尝试清除生成的文件

有时，生成文件中的错误是上一次编译残留的。即使你已经修正了 `.tex` 文件中的错误并重新编译，仍然包含错误的生成文件也可能还会被编译器读取，从而产生与之前相同的错误。你可以在重新编译之前尝试删除生成文件。关于在 Overleaf 中如何操作的说明可以在 [这里](/latex/zh-cn/zhi-shi-ku/028-clearing-the-cache.md).

如果即使删除所有生成文件并重新编译后，你仍然看到相同的错误，那么很可能是你的源文件中确实存在真实错误。

## 扮演侦探：定位生成文件中的错误

以下各节提供了一些寻找此类错误的技巧。我们将使用下面这个 *故意充满错误的* 示例项目来练习侦查。准备好了吗？开始吧！

[打开一个 *充满错误的* Overleaf 项目！](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Demo+of+LaTeX+compile+errors+reported+from+generated+files\&main_document=main.tex\&snip_uri=https%3A%2F%2Fassets.ctfassets.net%2Fnrgyaltdicpt%2F5qdEqgUidaYDHjOlBoKM7K%2F55395921a114edb36ed3d51d7b1c6edb%2Fdemoerrors.zip) 项目看起来应该像这样 😲：

![显示 LaTeX 项目错误的图片](/files/3cb8d01e630421afa2b0e44fbe3763486d20578e)

### .aux 文件中的错误

该 `.aux` 文件包含关于 `\label{...}` 声明和 `\cite{...}` 在 `.tex` 文件的使用信息，所以这些都是值得检查的内容。

让我们先看看这个来自我们示例错误项目的第一个错误。

![由于错误的 \label 声明导致 .aux 文件中的示例错误](/files/8b7969cbc9d861e2db1953dce345881966d5bec6)

错误 `Missing \endcsname inserted.` 在一个 `\alpha` 处，乍一看可能相当晦涩，似乎对我们的调试帮助不大。但从错误信息的文本（上下文）中我们可以看到，它发生在某段包含 `sec:\alpha`的代码附近，而这与编号为 1.1 的某个标签或计数器有关。因此，我们可能需要仔细检查 `\label{...}` 中任何包含片段 `.tex` 的 `sec:\alpha`.

你很快就会找到我们示例项目中的第 37 行：

```latex
\label{sec:\alpha}
```

传递给 `\label{...}` 的参数不应包含任何 LaTeX 命令或控制序列，例如 `\alpha`。因此，把标签改成类似 `\label{sec:alpha}`这样的形式，并同时修正任何对应的 `\ref{...}`，就可以清除这个错误。

下面是一个从 `.aux` 文件中报告出来的另一个错误，在我们的示例项目中：

![由于 \cite{...} 键中存在空格导致 .aux 文件中的示例错误](/files/1e8e291fe62aebd2be5b134c309665ddd61510fb)

这一次，编译器抱怨某个 `\citation`中有空白字符；其键以“That”开头。所以我们会想搜索 `\cite{That ...}` 中任何包含片段 `.tex` 文件……然后我们在第 23 行找到了它：

```latex
... justo \cite{That mandatory talk} eget magna ...
```

引用键不应包含空格字符，因此这个 `\cite{...}`中的空格，以及 `.bib` 文件中对应的 BIBTeX 键，都应被删除。

### .toc 文件中的错误

该 `.toc` 文件包含 `\tableofcontents`的条目。这些条目来自 LaTeX 文档中的各级标题，例如 `\chapter{...}`, `\section{...}`等等。因此，如果你看到来自 `.toc` 文件的错误报告，检查那些包含错误信息中提到文本的各级标题会很有用。

![由于 \section{...} 中未转义的 & 导致 .toc 文件中的示例错误](/files/88fd5257ccca6343d7f81c3bb4b04ef11f0913e3)

这看起来像是一个会被编号为“1”的分节标题，并且包含文本 `Introduction & Welcome`。在 `.tex` 文件中快速搜索会把我们带到第 12 行：

```latex
\section{Introduction & Welcome}
```

该 `&` 这里的 & 没有转义，因此我们需要把它改成 `\&` 在 `.tex` 文件中。

另一个类似的例子：

![由于 \section{...} 键中处于非数学模式的数学命令导致 .toc 文件中的示例错误](/files/a430270e88ef410a301e94712414aba01b28a53d)

同样，我们的猜测会是去寻找一个会被编号为“1.1”的分节标题，并且很可能包含 `Setting \alpha`。我们的猜测果然是对的，在 `.tex` 文件的第 36 行：

```latex
\subsection{Setting \alpha}
```

`\alpha` 是一个数学命令，但我们忘记在这里把它放入数学模式，所以需要改成

```latex
\subsection{Setting $\alpha$}
```

或

```latex
\subsection{Setting \(\alpha\)}
```

有时，错误会由于用于设置目录条目样式的代码中的错误而出现在 `.toc` 文件中：

![由于设置目录条目样式时代码不当导致 .toc 文件中的示例错误](/files/99f377167fcd2fd513393d919b9691e285d4652e)

这里，使用 `\itshae` 搜索会让我们找到示例 `.tex`第 5 行中的一个拼写错误：它应该是 `\itshape` 。在这种情况下，错误可以在我们 `.tex` 文件的导言区中找到，因此我们可以直接修正它。但如果你使用的是 `.cls` 或 `.sty` 文件，而且你怀疑错误是由所提供文件中的配置错误造成的，那么你应该联系模板或宏包的作者或维护者，让他们更新模板。

### .lof 和 .lot 文件中的错误

该 `.lof` 文件包含 `\listoffigures`，并由以下内容填充 `\caption{...}` 来自 `figure` 环境中的内容。

同样， `.lot` 文件使用来自 `\caption{...}` 环境的内容，为 `表格` \listoftables `生成条目。因此，如果来自`.

文件的 LaTeX 错误出现，你应该检查 `.lof` 或 `.lot` 其中包含相关文本片段的 `\caption{...}` 。根据这里的错误信息，我们会搜索

Effects of \alpha and var\_coeff `s，尤其是` 中任何包含片段 `\caption{...}`s： `figure`由于 figure \caption{...} 键中数学命令未处于数学模式导致 .lof 文件中的示例错误

![并在我们](/files/401799ac9492ba50432c4c633065b65d542d430d)

的第 19 行找到 `.tex` 文件的第 36 行：

```latex
\caption{Effects of \alpha and var_coeff}
```

该 `\alpha` 应放在数学模式中；而如果 `var_coeff` 本应是变量名，那么下划线需要转义。不要使用 `\verb|var_coeff|` ，因为这在 `\caption{...}`中也可能造成相当严重的问题！

```latex
\caption{Effects of $\alpha$ and \texttt{var\_coeff}}
```

同样地，看到这个错误时，我们会搜索 `some sample data with n^i` 中 `表格` `\caption{...}`，猜测我们也忘了把 `n^i` 放入数学模式。

![由于 table \caption{...} 键中上标未处于数学模式导致 .lot 文件中的示例错误](/files/bb2d33af43bfd94e42cc3962f991512ff6567510)

于是我们修正第 31 行

```latex
\caption{Some sample data with n^i}
```

设为

```latex
\caption{Some sample data with $n^i$}
```

### .bbl 文件中的错误

该 `.bbl` 文件包含参考文献列表（bibliography）的条目，并由 BIBTeX 在处理 `.bib` 文件后，使用来自 `.bst` 文件中的样式信息生成。来自 `.bbl` 的错误通常源于 `.bib` 文件中。

这里有一个我们在 Overleaf 支持中经常看到的常见错误：

![由于 .bib 文件中未转义的 & 导致 .bbl 文件中的示例错误](/files/f410b9748c32a85e747c179991658286a218d110)

搜索 `This & that` 在 `.bib` 会把我们带到示例项目的文件第 13 行，在那里我们意识到 `&` 应转义为 `\&` ，或者替换为单词 `和`.

```bibtex
    title   = {This & That},
```

作者经常会遇到与 Unicode 字符有关的错误，出现在 `.bbl` （以及因此出现在 `.bib`）文件中——尤其是在信息源是从别处复制粘贴来的情况下：

![由于 .bib 文件中不受支持的 Unicode 字符导致 .bbl 文件中的示例错误](/files/5cfa40ebb6c8c2db0adefcf7a0bdb5e21c895100)

把错误信息中的 ♣ 字符复制出来，并在 `.bib` 文件中搜索它，会把你带到第 3 行：

```bibtex
    title   = {Research ♣ Development},
```

某些 Unicode 字符不受 `latex` 和 `pdflatex` 编译器支持。为了避免该错误，你可以尝试 [更改项目的编译器](/latex/zh-cn/zhi-shi-ku/026-changing-compiler.md) 设为 `XeLaTeX` 或 `LuaLaTeX`。但即便如此，你仍需要确保项目与这些编译器兼容，并且你使用了包含能表示 ♣ 的字形的字体，以便它能在输出 PDF 中正确显示。因此，最好使用相关的 LaTeX 命令：

```bibtex
    title   = {Research $\clubsuit$ Development},
```

不过有时，这个字符可能更难被发现：

![由于 .bib 文件中不受支持、不可打印的 Unicode 字符导致 .bbl 文件中的示例错误](/files/b0160fb98895a57a60a3218e2cbbd3f5dc045edc)

这里，U+3000 是一个 [Unicode 字符 `IDEOGRAPHIC SPACE`](https://www.fileformat.info/info/unicode/char/3000/index.htm)，确实是一个空白字符。要从错误信息中复制这个确切字符以便在 `.bib` 文件中搜索，可能会很困难。所以我们得用另一种方法来定位它，即使用一个 `\DeclareUnicodeCharacter` 来替换 `U+3000` 为更显眼的东西！把下面这些行添加到你项目的导言区中，在 `\begin{document}`:

```latex
\usepackage{xcolor}
\DeclareUnicodeCharacter{3000}{\textcolor{red}{BAD!!}}
```

然后编译你的项目，错误就会消失；但你应该在输出 PDF 中仔细寻找 BAD!!：

![用红色 BAD!! 替换 U+3000 的输出 PDF](/files/463aee9af2885b8173344f8a917881c08d0f307d)

所以现在我们知道，这个坏字符位于 `来自` 和 `Wondrous`和“An Author”所写那条参考文献条目之间。它在 `.bib` 文件的第 5 行上看起来相当无害，因为它是不可见的：但如果你手动重新输入那段 `...of Wondrous...` ，用正常的空格键重新输入，重新编译后错误就会消失。

```bibtex
    journal = {Journal of　Wondrous Musings},
```

#### 关于 biblatex 的说明

如果你使用的是 `biblatex` 宏包，那么类似错误在 `.bib` 文件中很可能都会被报告为来自 `\printbibliography` 你 `.tex` 文件中的那一行。调试过程类似：使用错误信息中的短文本片段在你的 `.bib` 文件中搜索，以定位出错的行，并进行修正。

### .bst 文件中的错误

`.bst` 文件是 BIBTeX 用来处理和格式化参考文献列表的参考文献样式。如果你看到来自 `.bst` 文件的错误，这可能是由于 `.bst` 本身的 bug，尤其是当它是一个非常非常旧的样式文件时，可能已经不再与较新的 LaTeX 宏包兼容。但这也可能实际上是由于 `.bib` 文件中的错误。此类别中最常见的错误看起来是这样的：

![Bst-error-example-01.png](/files/188d174976d86321b1ccd8338b4203326ad0cc4c)

BIBTeX 键为 `Someone:etal:2008` 的条目具有 `author` 字段，位于 `.bib` 文件的第 36 行：

```bibtex
    author  = {Strange Someone, Night Stranger, and Random Person},
```

在一个 `.bib` 文件中， [多个姓名组成的列表](/latex/zh-cn/can-kao-wen-xian-he-yin-yong/01-bibliography-management-with-bibtex.md#multiple-authors) 应该用 `和`分隔，而不是逗号，也不是 `&`。因此这个 `author` 字段应更正为

```bibtex
    author  = {Strange Someone and Night Stranger and Random Person},
```

### .ttt 和 .fff 文件中的错误

只有在你加载 [`endfloat` 包](https://www.ctan.org/pkg/endfloat)时，这些文件类型才会被生成；它用于强制将所有表格和图形环境移动到文档末尾，以满足某些学术期刊在投稿时的要求。

要查看这些生成文件中的示例错误，请取消注释第 3 行 `\usepackage{endfloat}` 中的参数 `.tex` 文件（在我们的示例项目中）。

![Ttt-error-example-01.png](/files/5e4ad6e6ed155771f5c7e2a1b2f4c84bac6fbcab)

该 `.ttt` 文件包含文档中所有 `表格` 环境的内容，所以我们会搜索 `dummy & data` 在 `.tex` 文件，重点关注表格。我们会在 `.tex` 文件的第 29 行发现问题：我们有三列，比声明的两列多了一列。因此可能需要删除多出的一列；或者我们应该在 `\\` 之后插入 `dummy` 以开始新的一行；或者也许我们本来就打算声明三列 `c | c | c` ！

![Fff-error-example-01.png](/files/2609cbcbf4cc2bc3bbcafb241079cdd0f2b409d9)

同样， `.fff` 文件包含所有 `figure` 环境的内容，而搜索那个拼写错误的 `\includegraphcs` 会把我们带到 `.tex` 文件的第 18 行，在那里我们可以将其更正为 `\includegraphics`.

## 延伸阅读

* [Overleaf 是如何编译我的项目的？](/latex/zh-cn/zhi-shi-ku/064-how-does-overleaf-compile-my-project.md)
* [常见的 LaTeX 错误](/latex/zh-cn/latex-ji-chu/05-errors.md)
* [TeX FAQ 列表](https://texfaq.org/#errors)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/latex/zh-cn/zhi-shi-ku/066-how-to-find-and-fix-errors-reported-in-generated-files.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.