> 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/149-using-the-stop-on-first-error-compilation-mode.md).

# 使用“遇到第一个错误即停止”编译模式

本文介绍如何使用 Overleaf 的 **遇到首个错误即停止** 编译模式，并回顾一些重要的背景主题，包括：

* 什么是 [LaTeX 编译模式](#introduction-to-latex-errors-and-compilation)?
* [Overleaf 上的编译模式](#compilation-modes-on-overleaf)
* 如何 **遇到首个错误即停止** 可以是 [有助于调试](#benefits-of-using-the-stop-on-first-error-mode)

要跳过背景信息，你可以直接跳到解释……的部分 [如何启用“遇到首个错误即停止”编译模式](#the-stop-on-first-error-compilation-mode).

## LaTeX 错误与编译简介

将 LaTeX 文档转换为排版后的 PDF 文件，是一个称为……的过程的结果 *编译*：一个可执行程序，称为“LaTeX 编译器”，读取文档内容并执行其中的 LaTeX 命令，以生成排版后的 PDF 文件。

编写 LaTeX 标记（代码）时，犯错是很自然的，这些错误在编译过程中会导致编译器发出错误信息，试图解释编译器 *认为* 导致了问题。与其他编程语言一样，文档中的 LaTeX 代码只要有一个错误，就可能引发连锁错误，每个错误都有对应的信息。在 Overleaf 上，编译错误信息会通过 [位于……旁边的红色通知 **重新编译** 按钮](#overleafs-latex-error-reporting)，你可以点击 **日志和输出文件** 图标查看它们。

### 处理错误：编译模式

LaTeX 编译器，也称为 [TeX 引擎](/latex/zh-cn/shen-ru-wen-zhang/55-what-s-in-a-name-a-guide-to-the-many-flavours-of-tex.md)，内置了（用户可选择的） *编译模式* ，用于决定如何处理错误。以下项目符号列表使用 Overleaf 的 *专用说明性名称* 来表示这些模式：

* **尽管有错误仍尝试编译**——本质上是在遇到错误时仍继续尝试编译，寄希望于最好结果，可能会生成 PDF 文件，但其中也可能包含排版错误。
* **遇到首个错误即停止**——实际上是在出现问题的第一时间“退出”，向用户提供一条消息并在不创建 PDF 的情况下退出。这样可以避免随后引发一连串错误，让你专注于修复第一个错误并重新编译文档。
* **暂停编译以与用户交互**——暂停编译以提供帮助，并为用户提供修复错误并继续编译的机制。这在本地 LaTeX 安装中是可行的，但在 Overleaf 上不切实际。

## Overleaf 上的编译模式

为了管理 LaTeX 的编译过程，Overleaf 使用一个 [名为 latexmk 的构建工具](/latex/zh-cn/zhi-shi-ku/064-how-does-overleaf-compile-my-project.md) ，默认使用一种 Overleaf 称之为 **尽管有错误仍尝试编译：** 即使存在 LaTeX 编译错误，构建工具仍会尝试生成排版后的 PDF [LaTeX 编译错误](/latex/zh-cn/latex-ji-chu/05-errors.md).

在……中 **尽管有错误仍尝试编译** 在该编译模式下，LaTeX 编译器在检测到错误时不会停止；相反，它会“尽量猜测”用户的意图，并根据该猜测应用“修复”——有问题的代码也可能会被“跳过”。编译器 *可能* 会回到一种状态，使编译过程最终能够完成并创建 PDF，不过生成的 PDF 可能包含错误输出。通常，遇到的错误可能过于严重，或数量过多，LaTeX 编译器无法修复，因此它仍可能在不生成 PDF 的情况下“退出”。

### Overleaf 的 LaTeX 错误报告

如上所述，编译过程中生成的错误信息会通过位于……旁边的红色通知向用户报告 **重新编译** 按钮：

![显示 Overleaf 上报告的 LaTeX 错误的截图](/files/e02b6d6842fb2a196103c45792c5c7a69c462831)

你可以点击 **日志和输出文件** 图标以查看更多错误详情。例如，如果你错误地输入了 `\texbf{word}` 而不是 `\textbf{word}`，Overleaf 仍会显示编译后的 PDF 预览以及关于未定义命令的错误信息，但 PDF 中的“word”不会加粗！

## “遇到首个错误即停止”编译模式

用户现在可以通过切换到……来更改 LaTeX 编译模式 **遇到首个错误即停止** 该模式会使 Overleaf 在检测到第一个错误时立即终止编译。

### 如何启用“遇到首个错误即停止”

选择……旁边的小三角 **重新编译** 按钮，然后选择 **遇到首个错误即停止** 来自 **重新编译** 下拉菜单：

![显示如何启用“遇到首个错误即停止”编译模式的截图](/files/1d42e5cf4588ba30fea24e8ce72cfeb7bc859e1b)

#### 此模式设置的适用范围

该 **遇到首个错误即停止** 模式是按用户、按项目设置的。启用此模式将 *不* 影响你的其他项目，或同一项目中的任何协作者。

### 禁用“遇到首个错误即停止”

当 **遇到首个错误即停止** 已启用时，你可以通过选择蓝色按钮切换回默认编译模式 **禁用“遇到首个错误即停止”** ，该按钮位于出现编译错误时弹出的对话框中：

![显示编译失败消息的截图](/files/daeca6d1d0f95601be80d27bf34573d0cd61b652)

你也可以前往 **重新编译** 下拉菜单，并选择 **尽管有错误仍尝试编译** 模式：

![显示如何禁用“遇到首个错误即停止”编译模式的截图](/files/c47ba575ef82f81afb2d706c5d26ab78bf6dae20)

### 补充说明和建议

如果你的项目没有 LaTeX 编译错误，将照常显示 PDF 预览。如果你的项目 *会* 包含 LaTeX 编译错误，编译将在第一个错误处立即停止。第一个错误信息会如下方截图所示显示出来，这样你就可以专注于调试源代码中的错误。在此截图中，错误是由于不正确使用 `\caption{...}\label{...}` 在 tabular 环境中。第 15 行应移动到……之前 `\begin{tabular}`.

![显示典型 LaTeX 错误的截图](/files/72ef2bbfa5df800a1d5ee7b52ee0fe968289a074)

点击 **重新编译** 在更正每个错误后，再对后续每个编译错误重复此调试过程。当你的项目没有 LaTeX 错误时， **遇到首个错误即停止** 模式将显示成功编译的 PDF。

### 使用“遇到首个错误即停止”模式的好处

* **有助于调试编译超时。** 某些类型的编译错误非常严重（例如，意外递归），它们会阻塞 **尽管有错误仍尝试编译** 编译模式，导致 [编译超时](/latex/zh-cn/zhi-shi-ku/038-fixing-and-preventing-compile-timeouts.md#fatal-compile-errors-blocking-the-compilation) 在 Overleaf 项目中。启用 **遇到首个错误即停止** 模式可能有助于定位并调试此类错误。
* **不要让错误堆积起来。** 有些用户可能更喜欢其他 LaTeX 编辑器的行为，即编译过程会在遇到第一个 LaTeX 错误时停止，这样他们就可以在重新编译前修正错误。防止错误级联——引发一连串进一步的错误——可以避免调试 100 多条编译错误信息，这会变得很困难，也有些繁琐。
* **启用“遇到首个错误即停止”模式可以快速检测你的错误（如果有的话）。** 如果你有一份较大或较复杂、编译耗时更长的文档， **尽管有错误仍尝试编译** 该模式要求你等待编译完成。如果存在需要修复的错误，那么在看到第一个编译错误并尝试修复之前等待会很耗时。
* **学会调试错误是学习 LaTeX 的重要组成部分。** 该 **遇到首个错误即停止** 该模式可以帮助 LaTeX 初学者尽早学习并养成良好的 LaTeX 编码习惯，也许能加快他们掌握 LaTeX 的进程。LaTeX 错误看起来可能非常奇怪且深奥，因此很容易想忽略它们，让编译器继续运行——希望最终会出现一个 PDF，即使该 PDF 中包含排版错误。从长远来看，忽视编译错误会导致不良编码习惯，最终可能在将来让你吃亏，也许是在提交一篇重要期刊论文时！如果你正在教授 LaTeX 课程，学生可以使用 **遇到首个错误即停止** 模式来培养调试 LaTeX 错误的技能。

## 看起来并非源自你的文件的错误

如果你在……中手动停止编译 **尽管有错误仍尝试编译** 模式，然后启用 **遇到首个错误即停止**，下一次编译可能会出现一些看似随机的错误信息，例如 `! 文件在扫描 \@writefile 的使用时结束`，这些错误似乎并不是来自你的文件内部。这类错误可能是由于之前未完成的编译生成并残留的截断文件所致。在这种情况下，你可能需要执行 [从头重新编译](/latex/zh-cn/zhi-shi-ku/028-clearing-the-cache.md) 这样下一次编译，即便仍处于 **遇到首个错误即停止** 模式下，也有机会从干净状态开始并显示第一个相关错误。如果你仍然收到来自一个看似不存在的文件的错误——例如， `output.aux`, `output.toc` 等等——请查看 [此帮助页面](/latex/zh-cn/zhi-shi-ku/066-how-to-find-and-fix-errors-reported-in-generated-files.md).

## 一些更底层的细节

该 **尽管有错误仍尝试编译** 编译模式运行 `latexmk` 时使用以下标志：

```latex
latexmk -f -interaction=nonstopmode …
```

该 **遇到首个错误即停止** 编译模式则会改为使用以下标志运行 latexmk：

```latex
latexmk -halt-on-error -interaction=nonstopmode …
```

既然到了这里，你或许也会想进一步了解 [Overleaf 如何使用 `latexmk` 工具](/latex/zh-cn/zhi-shi-ku/064-how-does-overleaf-compile-my-project.md).


---

# 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/149-using-the-stop-on-first-error-compilation-mode.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.