> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-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) “可是我甚至都 **必须** 这个 `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 项目中点击“重新编译”按钮时会发生什么。

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

通常，生成的文件与 `.tex` 正在编译的文件具有相同的文件名；例如，如果你正在编译 `**main**.tex`，生成的文件将被命名为 `**main**.aux`, `**main**.toc`, `**main**.lof` 等等。不过， *在 Overleaf 上* 编译 `\\jobname` 始终设为 `**output**`，因此 [生成的文件](/latex/zh-cn/zhi-shi-ku/150-view-generated-files.md) 在你的 Overleaf 项目中总是命名为 `**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).

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

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

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

&#x20;[打开一个 *布满错误的* 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` 文件中：

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

`\alpha` 中，\alpha 是一个数学命令，但我们忘记在这里将其置于数学模式，所以需要改为

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

或

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

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

![因设置目录条目样式时使用了不正确的代码而导致的 .toc 文件示例错误](/files/99f377167fcd2fd513393d919b9691e285d4652e)

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

### 来自 .lof 和 .lot 文件的错误

该 `.lof` 文件包含 `\listoffigures`，并由……填充 `\caption{...}` 的一个记号值 `figure` 环境。

同样， `.lot` 文件使用 `\caption{...}` 来自 `table` 环境来生成……的条目 `\listoftables`.

因此，如果有来自 `.lof` 或 `.lot` 文件的 LaTeX 错误，你应检查 `\caption{...}` ，其中包含相关文本片段。

根据这里的错误信息，我们将搜索 `Effects of \alpha and var_coeff` 在我们的 `\caption{...}`的条目，尤其是 `figure`的条目：

![因图形 \caption{...} 键中的数学命令未处于数学模式而导致的 .lof 文件示例错误](/files/401799ac9492ba50432c4c633065b65d542d430d)

并找到我们 `.tex` 文件中：

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

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

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

同样，看到这个错误时，我们会搜索 `带有 n^i 的一些示例数据` 在 `table` `\caption{...}`，我们直觉认为忘记把 `n^i` 也放入数学模式了。

![因表格 \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!!：

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

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

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

#### 关于 biblatex 的说明

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

### 来自 .bst 文件的错误

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

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

具有 BIBTeX 键的条目 `Someone:etal:2008` 的 `author` 字段在 `.bib` 文件中：

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

在一个 `.bib` 文件的第 12 行， [多个姓名的列表](/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` 文件包含来自所有……的内容 `table` 环境中的内容，因此我们会搜索 `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://overleaf-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.