> 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/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\[草稿\]** 模式，并优化图片大小](#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 \[草稿] 模式编译

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

有一种方法可帮助判断是否是图像处理导致超时，那就是尝试以 **快速［草稿］** 模式进行编译。为此，请在 **快速［草稿］** 中选择 **重新编译菜单**。这会用方框替代所有图形，使 PDF 编译速度快得多：

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

如果你的文档能在 **快速［草稿］** 模式下编译，但无法在 **正常** 模式下完成编译，原因可能是图片文件过大或过多。

### 优化图片文件

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

* 对示意图和图表使用 PDF 文件，而不是 PNG 文件。
* 仅将 JPEG 用于照片。

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

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

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

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` 调用；或者如果你需要使用类似的方法进行调试，则使用 [`跟踪` 宏包](http://ctan.org/pkg/trace) 。

**使用 acro 宏包**

使用 [`acro` 宏包](https://www.ctan.org/pkg/acro) 必须 [的用户报告说第 3 版加载缩写定义很慢](https://github.com/cgnieder/acro/issues/205) 。其 `acro`编译时间增加的一个后果是可能触发编译超时；幸运的是，有一个变通方法：使用 `acro` 宏包。

从第 3 版切换回第 2 版可能需要编辑你的项目，以确保其与第 2 版的选项、功能和命令兼容。第 2 版文档可用，包含在较早的源代码版本中，这些版本可以 [从 GitHub 下载](https://github.com/cgnieder/acro/releases/tag/v2.10).

在回退到第 2 版时检查以下项目——此列表远非穷尽：

1. 修改你项目的主 `.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 命令极少数情况下会触发“无限循环”。无限循环最常见的原因是宏包或用户自定义命令中的错误。

如果你怀疑自己遇到了循环，请检查是否不小心创建了一个 [递归](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{...} 应位于 tabular 环境之外
          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-biao-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`的参数列表末尾的

**s.**

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

**使用 babel 宏包**

某些 [`babel`](https://ctan.org/pkg/babel) 语言选项会改变某些字符的含义，当这些字符在其“正常”上下文中使用时可能会引发问题；例如，在数学模式下。为避免此问题，请尝试使用选项 `shorthands=off` 在加载 babel 时（例如， `\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)所述。如果你点击红色气泡，就会看到错误消息。点击每条错误消息会将你带到源代码中的相应行，以便你更正代码。我们建议尽快修正错误，因为任其累积可能会在将来导致难以调试的致命错误。

[此页面](/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://overleaf-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.