> 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-tw/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-tw/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-tw/zhi-shi-ku/064-how-does-overleaf-compile-my-project.md) ，預設使用 Overleaf 稱為 **即使有錯誤仍嘗試編譯：** 該建置工具會嘗試產生排版後的 PDF，即使存在 [LaTeX 編譯錯誤](/latex/zh-tw/latex-ji-chu/05-errors.md).

在 **嘗試在有錯誤的情況下仍然編譯** 在這種編譯模式下，LaTeX 編譯器在偵測到錯誤時不會停止；相反地，它會嘗試「猜測」使用者的意圖，並根據該猜測套用「修正」——問題程式碼也可能會被「跳過」。編譯器 *可能* 會回到某個狀態，使編譯過程最終能完成並產生 PDF，雖然產生的 PDF 可能含有錯誤輸出。通常，遇到的錯誤可能太嚴重，或數量太多，以致 LaTeX 編譯器無法修正，因此它仍可能在沒有產生 PDF 的情況下「放棄」。

### Overleaf 的 LaTeX 錯誤回報

如上所述，編譯期間產生的錯誤訊息會透過顯示在 **重新編譯** 按鈕旁的紅色通知回報給使用者：

![顯示 Overleaf 上回報的 LaTeX 錯誤之截圖](/files/edafceb0e995aa5f7e568598359c300e3caf4883)

你可以點擊 **記錄與輸出檔案** 圖示，查看更多錯誤詳細資訊。例如，如果你不小心輸入了 `\texbf{word}` 而不是 `\textbf{word}`，Overleaf 仍會顯示已編譯的 PDF 預覽以及關於未定義指令的錯誤訊息，但 PDF 中的「word」不會是粗體！

## 在第一個錯誤時停止的編譯模式

使用者現在可以透過切換到 **遇到第一個錯誤即停止** 模式來變更 LaTeX 編譯模式，這會使 Overleaf 在偵測到第一個錯誤時立即終止編譯。

### 如何啟用「在第一個錯誤時停止」

選取 **重新編譯** 按鈕旁的小三角形，然後選擇 **遇到第一個錯誤即停止** 來自 **重新編譯** 下拉式選單中：

![顯示如何啟用「遇到第一個錯誤即停止」編譯模式的螢幕截圖](/files/cb00bd25d8efda227d0f4637dfca0fc8cfd165cc)

#### 此模式設定的適用範圍

該 **遇到第一個錯誤即停止** 模式是按使用者、按專案設定。啟用此模式將 *不* 影響你的其他專案，或同一專案中的任何協作者。

### 停用「在第一個錯誤時停止」

當 **遇到第一個錯誤即停止** 啟用時，你可以透過選取藍色按鈕 **停用「在第一個錯誤時停止」** 來切回預設編譯模式，此按鈕位於發生編譯錯誤時出現的對話方塊中：

![顯示編譯失敗訊息的截圖](/files/0d1e6ff8363c6345e574e4ed74d0a95d8e0ab32d)

你也可以前往 **重新編譯** 下拉式選單，並選取 **嘗試在有錯誤的情況下仍然編譯** 模式：

![顯示如何停用「在第一個錯誤時停止」編譯模式的截圖](/files/852330413bec3e37eedd90f717f88cbcd00008f0)

### 其他注意事項與建議

如果你的專案沒有 LaTeX 編譯錯誤，將會照常顯示 PDF 預覽。如果你的專案 *確實* 包含 LaTeX 編譯錯誤，編譯將會在第一個錯誤處立即停止。第一個錯誤訊息會如下面的截圖所示顯示，讓你能專注於除錯原始碼中的錯誤。在這張截圖中，錯誤是由於不正確使用 `\caption{...}\label{...}` 在 tabular 環境中。第 15 行應移到 `\begin{tabular}`.

![顯示典型 LaTeX 錯誤的截圖](/files/55a7242e566a2ef784b39841fa46e8bed0d4949d)

點擊 **重新編譯** 在修正每個錯誤之後，然後對後續每個編譯錯誤重複這個除錯流程。當你的專案沒有 LaTeX 錯誤時， **遇到第一個錯誤即停止** 模式將顯示成功編譯的 PDF。

### 使用「在第一個錯誤時停止」模式的好處

* **有助於除錯編譯逾時。** 有些類型的編譯錯誤非常嚴重（例如意外遞迴），它們可能會阻塞 **即使有錯誤仍嘗試編譯** 編譯模式，導致 Overleaf 專案中的 [編譯逾時](/latex/zh-tw/zhi-shi-ku/038-fixing-and-preventing-compile-timeouts.md#fatal-compile-errors-blocking-the-compilation) 。啟用 **遇到第一個錯誤即停止** 模式可能有助於定位並除錯這類錯誤。
* **別讓錯誤堆積起來。** 有些使用者可能偏好其他 LaTeX 編輯器的行為，也就是編譯過程會在遇到第一個 LaTeX 錯誤時停止，讓他們可以在重新編譯前修正錯誤。防止錯誤連鎖——引發更多錯誤的雪崩效應——可避免必須除錯 100 多條編譯錯誤訊息，這會變得很困難且有些繁瑣。
* **啟用「在第一個錯誤時停止」模式可以快速偵測你的錯誤（如果有的話）。** 如果你有一份大型或複雜、編譯時間較長的文件， **嘗試在有錯誤的情況下仍然編譯** 模式會要求你等待編譯完成。如果有錯誤需要修正，你必須等待到看到第一個編譯錯誤並嘗試修正，這可能相當耗時。
* **學會除錯錯誤是學習 LaTeX 的重要一環。** 該 **遇到第一個錯誤即停止** 模式可以幫助 LaTeX 初學者及早學會並養成良好的 LaTeX 程式設計習慣，也許能加快他們精通 LaTeX 的進程。LaTeX 錯誤看起來往往十分怪異且晦澀，因此很容易讓人想忽略它們，並讓編譯器繼續跑——希望最終會出現 PDF，即使該 PDF 含有排版錯誤。長遠來看，忽略編譯錯誤可能導致不良的程式設計習慣，最終在未來讓你吃虧，也許是在提交重要期刊論文時！如果你正在教授 LaTeX 課程，你的學生可以使用 **遇到第一個錯誤即停止** 模式來培養除錯 LaTeX 錯誤的能力。

## 看起來並非來自你的檔案的錯誤

如果你手動在 **嘗試在有錯誤的情況下仍然編譯** 模式中停止編譯，然後啟用 **遇到第一個錯誤即停止**，下一次編譯可能會出現一些看似隨機的錯誤訊息，例如 `! 檔案在掃描 \@writefile 的使用時結束`，看起來並不是來自你的檔案。這類錯誤可能是由前一次未完成編譯所產生、並殘留的截斷檔案所致。在那種情況下，你可能會想要執行 [從頭重新編譯](/latex/zh-tw/zhi-shi-ku/028-clearing-the-cache.md) ，以便下一次編譯仍在 **遇到第一個錯誤即停止** 模式下，有機會從乾淨的狀態開始，並顯示第一個相關錯誤。如果你仍然從一個看似不存在的檔案得到錯誤——例如 `output.aux`, `output.toc` 等——請參閱 [這個說明頁面](/latex/zh-tw/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-tw/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-tw/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.