> 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/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-du-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 编译错误](/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 预览以及关于未定义命令的错误信息，但 “word” 不会在 PDF 中加粗！

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

用户现在可以通过切换到 **遇到首个错误即停止** 该模式让 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 错误的技能。

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

如果您手动在 **尽管有错误仍尝试编译** 模式下停止编译，然后启用 **遇到首个错误即停止**，下一次编译可能会产生一些看似随机的错误信息，例如 `! File ended while scanning use of \@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://ayakaleaf-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.