> 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/038-fixing-and-preventing-compile-timeouts.md).

# 修复并防止编译超时

当你点击 **重新编译** Overleaf 项目中的按钮时，你会启动一个过程，它会读取你的项目文件并将它们转换为排版好的 PDF。如果你遇到编译超时错误，这意味着编译过程无法在 [你的 Overleaf 套餐的超时限制内完成](/latex/zh-cn/zhi-shi-ku/119-overleaf-plan-limits.md).

虽然有些项目可能过大或过于复杂，无法在给定时间内生成 PDF，但编译超时通常是可以修复或避免的。

## 解决编译超时的步骤

按照以下步骤识别并修复导致编译超时的常见问题：

1. [检查编译错误，并使用 **遇到首个错误即停止** 模式](#first-errors)
2. [尝试 **Fast\[draft\]** 模式，并优化你的图片大小](#second-images)
3. [评估你的项目中是否存在耗时任务](#third-assess)

除了遵循这些步骤外，也请查看关于在 [特定超时情形](#anchor-advice) 下该怎么做，以及应遵循哪些 [最佳实践](#anchor-best) 以防止编译超时的建议。

虽然许多项目可以在 Overleaf 免费套餐提供的时间内完成编译，但如果你正在准备一个大型或复杂的文档，你可能需要 [订阅高级套餐](https://www.overleaf.com/user/subscription/plans) 以获得更多编译时间。

## 第 1 步：检查编译错误并修复

某些编译错误，或多个错误的累积，可能会完全阻止 [latexmk 构建过程](https://learn.overleaf.com/learn/Kb/How_does_Overleaf_compile_my_project%3F) 并导致编译超时。要查找并修复错误，请在 **遇到首个错误即停止** 编译模式下的 **重新编译** 下拉菜单中启用：

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

该 [**遇到首个错误即停止**](/latex/zh-cn/zhi-shi-ku/149-using-the-stop-on-first-error-compilation-mode.md) 编译模式的作用正如你所期望的那样——一旦遇到错误，它就会立即停止编译。发生这种情况时，不会生成 PDF，并会显示一条描述该错误的信息。启用 **遇到首个错误即停止** 后，你可以找出并修复项目中的每一个错误，直到项目不再有错误为止。

点击每条错误信息会带你到源代码中导致问题的那一行，这样你就可以修正代码。若干常见错误在 [此页面](/latex/zh-cn/latex-ji-chu/05-errors.md)中有说明，并且一些 LaTeX 调试建议列在 [此页面](/latex/zh-cn/wen-da/81-tips-and-tricks-for-troubleshooting-latex.md)。另请参阅本文中的 [这一部分](#anchor-fatal) ，其中列出了一些常见的 **致命编译错误** ，它们会导致编译超时。

## 第 2 步：尝试在 Fast \[draft] 模式下编译

在项目中包含大量或大型图片文件会显著增加编译项目所需的时间。

一种有助于判断图片处理是否是超时原因的方法，是尝试在 **Fast \[draft]** 模式下编译。为此，请选择 **Fast \[draft]** 选项，位于 **重新编译菜单**中。这样会用方框替代所有图形，使 PDF 编译速度快得多：

![Overleaf 项目草稿编译模式设置](/files/2217eb96220fb0d7e81b6715fe0ec56c0372c9b2)

如果你的文档可以在 **Fast \[draft]** 模式下编译，但在 **Normal** 模式下无法完成编译，原因可能是图片文件过大或数量过多。

### 优化图片文件

如果你使用了多个大型、高分辨率的 PNG 或 JPEG 文件，处理这些文件会增加编译项目所需的时间，有时甚至会大幅增加。请务必：

* 图表和绘图请使用 PDF 文件而不是 PNG 文件。
* JPEG 仅用于照片。

如需更多建议，请参阅： [优化大型图片文件](/latex/zh-cn/zhi-shi-ku/113-optimising-very-large-image-files.md).

## 第 3 步：评估你的项目中是否存在耗时任务和致命错误

如果两者 **遇到首个错误即停止** 和 **Fast\[draft]** 编译模式仍然导致编译超时，你可能需要进一步查看，以识别编译超时的原因并（希望）加以解决。

1\. [查看可能减慢编译速度的耗时做法和包列表](#anchor-slow)

2\. [查看可能导致超时的常见致命错误列表](#anchor-fatal)

3\. [查看最符合你情况的特定超时场景建议](#anchor-advice)

### 耗时做法和包

某些做法和宏包会导致编译非常慢，甚至超时。

**包含复杂的 TikZ 或 pgfplots 绘图**

`TikZ` 和 [`pgfplots`](https://ctan.org/pkg/pgfplots?lang=en) 可以生成很棒的图形，但它们 [编译时间可能很长](https://tex.stackexchange.com/a/254946/226)。你可以通过 [几种方式将 TikZ 图片外部化](/latex/zh-cn/wen-da/60-i-have-a-lot-of-tikz-matlab2tikz-or-pgfplots-figures-so-i-m-getting-a-compilation-timeout.-can-i.md) ，这样 LaTeX 就不必在每次生成新 PDF 时重新绘制它们。

**使用 mhchem 宏包**

最新版本的 [`mhchem` 包](https://ctan.org/pkg/mhchem?lang=en) 编译可能更慢。根据你的用途， [`chemformula` 包](https://ctan.org/pkg/chemformula) 可能会减少编译所需时间。如果你已经在使用 `mhchem`，你可以尝试直接将其替换为 `chemformula` ：

```latex
% \usepackage{mhchem}
\usepackage{chemformula}
\let\ce\ch
```

* **注意**： `mhchem` 和 `chemformula`和 `\ce{2H2O}` 的语法和功能存在差异，所以这并不总是能很好地工作。例如， `mhchem`下可以正常显示，但在 `chemformula` 下你必须把它写成 `\ch{2 H2O}` ，并在开头的 `2`.

**包含跟踪或调试调用**

如果你的文档里碰巧有一个 `\tracingall` 命令，它可能会把 *大量* 数据写入 `.log`。记录并处理 `\tracingall` 文件中的数据 `.log` 会使编译变得极其缓慢。建议移除这些 `\tracingall` 调用；如果你需要使用类似方法进行调试，请改用 [`trace` 包](http://ctan.org/pkg/trace) 。

**使用 acro 宏包**

的用户 [`acro` 包](https://www.ctan.org/pkg/acro) 报告说 3 版在 [加载缩略语定义时速度很慢。](https://github.com/cgnieder/acro/issues/205) 带来的一个后果是 `acro`编译时间增加，可能会触发编译超时；幸运的是，有一个解决办法：使用该 `acro` 宏包。

宏包的 2 版。 [从 3 版切回 2 版可能需要编辑你的项目，以确保它与 2 版的选项、功能和命令兼容。2 版的文档可用，包含在更早的源代码发布中，可从](https://github.com/cgnieder/acro/releases/tag/v2.10).

从 GitHub 下载

1. 在回退到 2 版时，以下是一些需要检查的项目——这份列表远非穷尽： `.tex` 将你的项目主
   * 修改为： `\usepackage{acro}` 设为 `\usepackage{acro}[=v2]`
   * 更改 `include=...` 选项键 `\printacronyms` 设为 `include-classes=...`
2. 在任何 `\DeclareAcronym` 命令中，确保 `tag=...` 选项键改为 `class=...`.

请参阅 [`acro` 2.10 版文档](https://github.com/cgnieder/acro/releases/tag/v2.10) ，了解 2 版中可用但 3 版中不可用的命令和选项。

**使用 EPS 或 SVG 图片**

使用 EPS 或 SVG 图片可能需要额外处理，将其转换为 PDF 格式。这种额外处理会增加编译项目所需的时间。

* 虽然 **latex** 编译器会直接支持 EPS 图片，但 **pdfLaTeX** 编译器不支持 EPS 图片，因此在使用该编译器时，需要额外一步将这些图片转换为 pdf 图片。该处理由 `epstopdf` 宏包完成，它使用 `Ghostscript` 将 EPS 文件转换为 PDF。这个转换步骤会显著增加编译项目所需的时间。
* 任何 LaTeX 编译器都不能直接支持 SVG 图片文件，因此需要使用 `svg` 宏包以及它提供的 `\includesvg` 命令。该 `svg` 宏包使用 `inkscape` 将 SVG 图片转换为 PDF。这个转换步骤会显著增加编译项目所需的时间。

为了获得更快的结果并帮助避免编译超时，请使用图片的 PDF 版本，而不是 EPS 或 SVG 格式。

**使用 tabularray 宏包**

该 `tabularray` 宏包为在 LaTeX 中实现表格提供了对标准命令和环境的替代方案。不幸的是，该 `tabularray` 宏包运行非常缓慢，尤其是对于较大的表格以及使用某些列类型的表格。目前，出于编译时间方面的考虑，建议使用标准的表格定义方法，而不是 `tabularray` 。

**在命令中创建无限循环**

在编译过程中，LaTeX 命令偶尔会触发“无限循环”。无限循环最常见的原因是宏包中的 bug，或用户自定义命令中的 bug。

如果你怀疑自己可能遇到了循环，请检查你是否无意中在某个自定义命令中创建了一个 [递归](https://en.wikipedia.org/wiki/Recursion) 定义，例如 `\newcommand{\foo}{\foo}`.

### 致命编译错误的一些原因

下面是一些已知的致命错误原因。

**在对标题敏感的命令中包含空行**

LaTeX 类和期刊模板通常会提供特殊命令来设置文档标题的某些部分。这些命令通常只适合包含简单参数，以意想不到的方式使用它们可能会导致编译错误，甚至超时。最重要的是，像 `\author{...}`, `\date{...}` 和 `\title{...}` 这样的命令不应包含空行。

**包含过多固定浮动体**

如果你有过多使用 `[H]` 位置标识符的表格或图形，它们来自 `float` 宏包，LaTeX 可能会陷入无限循环，试图为所有这些内容找到合适的位置。可以考虑将所有 `[H]` 配合 `[hbt!]` 替换为，必要时偶尔使用 `\clearpage` ，以便在插入分页符之前清空队列中的所有表格和图形。

**\caption 命令和 tabular 环境中的错误**

以下是需要注意的表格相关问题列表——一般来说，在排版表格时请务必小心！

* `\caption{...}` 应始终放在 *外部* 该 `tabular` 环境之外，因为如果加载了 [`caption` 包](https://ctan.org/pkg/caption) 宏包，它可能会导致致命错误，如下例所示：

  ```latex
  \documentclass{article}
  \usepackage{caption}
  \begin{document}

  \begin{table}
      \begin{tabular}{c|c}
          \caption{Caption}% \caption{...} should be OUTSIDE the tabular environment
          a & b \\
          c & d \\
      \end{tabular}
  \end{table}
  \end{document}
  ```

  [打开此示例 **它会触发 Overleaf 超时错误**](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Overleaf+timeout+example\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bcaption%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Cbegin%7Btable%7D%0A++++%5Cbegin%7Btabular%7D%7Bc%7Cc%7D%0A++++++++%5Ccaption%7BCaption%7D%25+%5Ccaption%7B...%7D+should+be+OUTSIDE+the+tabular+environment%0A++++++++a+%26+b+%5C%5C%0A++++++++c+%26+d+%5C%5C%0A++++%5Cend%7Btabular%7D%0A%5Cend%7Btable%7D%0A%5Cend%7Bdocument)
* 相比之下，请注意 `longtable` 环境 *确实* 要求 `\caption{...}` 在其中使用，如我们 [表格帮助文章](/latex/zh-cn/tu-xing-he-biao-ge/01-tables.md#multi-page-tables).
* `\caption{...}` 中所示， `\\`, `\newline`, `\centering`, `\raggedright` 等不应包含
* 在某些模板或宏包中， `\ref{...}` 或 `\cite{...}` 在 `\caption` 中可能需要在前面加上 `\protect` 以避免致命错误；例如， `\protect\cite{...}`.
* 检查不完整的 `\cmidrule{...}` 在 `tabular` 环境；它需要一段列范围，因此你需要写 `\cmidrule{3-3}` 而不是仅写 `\cmidrule{3}` ，如果你想要只跨一列的水平线。
* 避免嵌套 `tabular` 环境。若你想在表格单元格中手动换行，可以看看 [`makecell` 包](https://ctan.org/pkg/makecell?lang=en) ；或者如果你在寻找创建可自动换行长文本列的方法，可以看看 `p{...}` 列类型和/或 [`tabularx`](https://ctan.org/pkg/tabularx) 宏包。
* 如果你的 tabular 行以 `[...` 开头，你可能需要在 `\relax` 之后添加 `\\` ，即上一行中的

**使用 soul 或 changes 宏包**

如果你正在使用 [`soul`](https://ctan.org/pkg/soul) 或 [`changes`](https://ctan.org/pkg/changes) 宏包来高亮文本或删除文本，那么 `\cite` 和 `\ref` 中可能需要在前面加上 `\protect`；例如， `\protect\cite{...}`.

**使用 tikzpicture**

检查是否缺少 `;` 在 path/node 命令末尾的 `]` 以及在 `tikzpicture`参数列表末尾的

**。**

该 [`使用 breqn 宏包`](https://ctan.org/pkg/breqn) breqn `宏包的` dmath `环境可能会陷入无限循环；请改用` align

**使用 babel 宏包**

某些 [`babel`](https://ctan.org/pkg/babel) 语言选项会改变某些字符的含义，当这些字符在其“正常”上下文中使用时可能会引发问题；例如在数学模式中。为避免这种情况，请尝试在加载 babel 时使用选项 `shorthands=off` （例如， `\usepackage[shorthands=off]{babel}`).

**使用 jabbrv 宏包**

有些模板使用 [`jabbrv` 包](https://github.com/compholio/jabbrv) 来自动缩写期刊标题（见 [此 Overleaf 示例](https://www.overleaf.com/latex/templates/automatic-journal-abbreviations/mxfsdscmvxcr)）。当 `.bib` 文件中的期刊字段包含带重音的 Unicode 字符（例如 Biología）时，这会阻止编译并在 Overleaf 上导致超时。此时应使用 LaTeX 命令代替，例如 `Biolog{\'i}a` ，或者你可以 [更改项目的编译器](/latex/zh-cn/zhi-shi-ku/026-changing-compiler.md) 设为 `XeLaTeX` 或 `LuaLaTeX`，这两者都内置支持读取 Unicode 字符。

## 针对某些特定超时情形的建议

### 我的项目之前编译没有任何错误，但现在我看到了编译超时

一个小改动有时就会导致编译超时。为帮助识别问题原因并修复它，请尝试以下步骤：

1. 使用 [从头重新编译](/latex/zh-cn/zhi-shi-ku/028-clearing-the-cache.md) 来清除任何可能造成问题的过时生成文件。
2. 使用 [Overleaf 历史功能](/latex/zh-cn/geng-duo-zhu-ti/49-using-the-history-feature.md) 来查找你最近的更改。请参阅上面的致命编译错误原因列表。
3. 使用 [遇到首个错误即停止](/latex/zh-cn/zhi-shi-ku/149-using-the-stop-on-first-error-compilation-mode.md) 选项来查找并修复你无意中引入的任何错误。

有可能一个小改动已经导致了致命编译错误——请参阅 [上面的致命编译错误列表](#anchor-fatal) 以了解一些可能的原因。

### 我刚把一个项目上传到 Overleaf，就遇到了编译超时

这可能是因为你的项目缺少关键文件或宏包，或者其组织方式给 Overleaf 的编译过程造成了问题。

* 如果一个项目在你本地机器上编译没有问题，但在 Overleaf 上无法编译，那么可能是你在自己的电脑上使用了不同版本的 **TeX Live** 。你可以 [更改项目的 TeX Live 版本](https://www.overleaf.com/blog/new-feature-select-your-tex-live-compiler-version) ，使其更接近你在本地成功编译该项目所使用的版本。
* 你上传的项目可能没有适合 Overleaf 的最佳文件结构。如果你的主 tex 文件位于某个文件夹中，编译器可能难以定位某些文件依赖项。如果你的主 tex 文件位于某个文件夹中，请尝试重新组织项目，使主 tex 文件位于项目的顶层。

遵循 [上面的查找和修复错误说明](#first-errors) 通常可以识别缺失文件、TeX Live 版本问题以及项目组织问题。

### 我复制了一个原本可以编译的项目，但现在我遇到了编译超时

新项目，包括现有项目的副本，默认会使用最新版本的 TeX Live。如果你的原始项目使用的是较旧版本的 TeX Live，那么最近版本可能存在不兼容，从而导致问题。尝试 [更改 TeX Live 版本](https://www.overleaf.com/blog/new-feature-select-your-tex-live-compiler-version) 在新副本中将其版本调整为与原始项目一致。

### 当我包含所有章节时，项目无法编译，但每个章节单独编译都没有问题

按照 [上面关于使用 Fast\[draft\] 编译选项的建议](#second-images) 以查看整个项目是否可以在 Fast\[draft] 模式下编译。

在某些情况下，可以分两步成功编译一个大型项目：先在 Fast\[draft] 模式下运行，然后再在 Normal 模式下编译。

检查项目的每个部分，以找出可能导致编译缓慢的来源。这些可能包括 [可以优化的大型图像文件](#anchor-optimize)，或其他 [耗时的做法或宏包](#anchor-slow).

### 我的项目有时会超时，但无法稳定编译

你的项目可能已经非常接近最大编译时间限制。请遵循上面的建议来 [修复错误](#first-errors), [优化图片](#second-images)、以及 [避免耗时的做法或宏包](#third-assess).

## 防止编译超时的最佳实践

与其在编译超时发生后再处理那些有时令人紧张的修复过程，不如提前防止它发生要好得多。这些建议应能帮助你防止编译超时的发生，或在发生时快速恢复。

### 在编译错误发生时立即修复所有错误

编译错误会如在 [此页面](/latex/zh-cn/wen-da/81-tips-and-tricks-for-troubleshooting-latex.md)中所述那样，通过 Recompile 按钮旁边的红色通知气泡来提示。如果你点击红色气泡，就会看到错误信息。点击每条错误信息会带你到源代码中相应的行，这样你就可以更正代码。我们建议尽快修正错误，因为让错误积累起来，未来可能会导致难以调试的致命错误。

[本页](/latex/zh-cn/latex-ji-chu/05-errors.md) 解释了几种常见的编译错误。如果你在理解某条错误信息时遇到困难，通常可以使用错误中的文本在网上搜索，这样你会找到解释该错误并提供解决方案的博客或论坛帖子。

### 在重大更改或重要里程碑之前为项目版本打标签

使用 [Overleaf 历史功能](/latex/zh-cn/geng-duo-zhu-ti/49-using-the-history-feature.md) 为你的项目版本打标签，这样你就可以轻松比较当前项目与早期版本。这有助于你快速找出新的编译错误来源。

### 整理你的文件

如果你的项目组织得很好，就更容易发现并解决问题。此外，良好的项目管理可以让你编译项目的特定部分，从而更容易找出可能导致编译时间异常长的区域。请 [参见此处](/latex/zh-cn/wen-dang-jie-gou/07-management-in-a-large-project.md) 以获取管理大型项目的建议。

## 关于编译和编译时间的更多信息

### 到底什么是“编译”？

编译是将你的 LaTeX 代码转换为排版后的 PDF 文件的过程。 [进一步了解 Overleaf 如何编译 LaTeX 项目](/latex/zh-cn/zhi-shi-ku/064-how-does-overleaf-compile-my-project.md).

### 合理使用限制

一些大型或复杂的文档编译时间可能会超过 Overleaf 免费方案上的超时限制，并且可能需要我们 [付费方案](https://www.overleaf.com/user/subscription/plans)中提供的更长编译时间。某些项目甚至可能需要比我们的付费方案所提供时间更长的编译时间。在这些情况下，你可能需要下载项目并在本地编译。

### 还卡住吗？

如果你遇到一个无法根据这里的建议解决的编译超时问题，请 [告知我们](https://www.overleaf.com/contact).


---

# 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/038-fixing-and-preventing-compile-timeouts.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.