# 编译

编译 LaTeX、Typst 和 Markdown 项目，为每种引擎选择编译选项，阅读日志，并控制离线时的宏包获取。

新的 LaTeX 项目从**设置 → 引擎 → LaTeX**中的默认编译引擎开始。开箱即用的是 **Tectonic**，一个基于 XeTeX、随 Oleafly 一起提供的引擎。当项目需要传统的 TeX 工具链时，你也可以使用 `latexmk`，可以只用于一个项目，也可以设为默认。Typst 项目使用内置的 Typst 或项目固定的其他版本编译，Markdown 项目则经由 Pandoc 和 Tectonic 处理。LaTeX 编译器和 Typst 版本属于项目本身，所以更改一个项目不会影响其他项目。

## 开始编译

![使用项目工具栏中的重新编译；它旁边的箭头会打开编译选项。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵（Ctrl+Enter），在任何地方都可以。
- 工具栏右上角的**编译**按钮。项目有了结果之后，它会显示为**重新编译**。
- ⌘K 命令面板中的**重新编译**。
- 将项目打开到显示 PDF 窗格的视图时，会自动编译一次，这样你看到的就是最新的预览。
- 在终端或脚本中运行 `oleafly build`。参见[命令行工具](/docs/cli/)。

编译总是先保存当前文件，所以 PDF 与你看到的内容一致。如果你处于仅编辑器视图，编译会展开分屏视图，让你看到结果。

## 编译选项

**重新编译**旁边的箭头会打开编译选项。菜单只显示对项目引擎有作用的选项。

| 分组 | 使用 Tectonic 的 LaTeX | 使用 `latexmk` 的 LaTeX | Typst | Markdown |
|---|---|---|---|---|
| **自动编译** | 是 | 是 | 是 | 是 |
| **编译模式**（常规或快速） | 是 | 否 | 否 | 否 |
| **语法检查** | 是 | 是 | 否 | 否 |
| **编译器（本项目）** | 是 | 是 | 否 | 否 |
| **Typst 版本**、**字体**、**构建**、**变体** | 否 | 否 | 是 | 否 |
| **编译错误处理** | 是 | 是 | 否 | 否 |

**停止编译**和**从头重新编译**位于每种引擎菜单的底部。Typst 项目有了构建变体之后，才会出现**变体**分组。

在**编译器（本项目）** 下，**Tectonic** 是内置的。**自动**通过 `latexmk` 运行你的系统 TeX，并根据源码选择编译器。**pdfLaTeX**、**XeLaTeX** 和 **LuaLaTeX** 会固定使用那个编译器，同样通过 `latexmk` 运行，**upLaTeX** 和 **pLaTeX** 用来编译日文文档。除 Tectonic 外，每个选项都需要 TeX 发行版。如果这台电脑上没有，选择它们时 Oleafly 会提议安装 TinyTeX。请参阅[没有安装 TeX 时](/docs/latex-engines/#when-no-tex-is-installed)。Typst 的各个分组在 [Typst 项目](/docs/typst/)中介绍。

## 自动编译

在编译选项中把**自动编译**设为**开启**，或在 ⌘K 面板中运行**启用自动编译**。它默认关闭，对所有项目生效，同样的控件也可以再把它关掉。

在 LaTeX 或 Markdown 项目中，Oleafly 会在你停止输入约 2.5 秒后重新编译。只有真正的编辑才会触发它。切换标签页或打开文件不会。

在 Typst 项目中，自动编译就是实时预览。Oleafly 让一个 Typst 进程持续运行，打开的文件会在你停止输入片刻后自动保存，PDF 会在相同的滚动位置刷新。请参阅[用自动编译实时预览](/docs/typst/#live-preview-with-auto-compile)。

编译不会堆积。如果你在自动编译运行时继续编辑，Oleafly 会停止它，并用你最新的文本重新开始，让 PDF 更快跟上。当编译是你或智能体启动的、正在下载宏包、快要完成，或者它本身就是一次重启时，Oleafly 会让它完成。在这些情况下，只会排队一次后续编译，所以最终的 PDF 仍然反映你最新的编辑。

## 查看进度

构建期间，预览顶部会有一条细细的进度条，第一份 PDF 出现之前，窗格会显示一个百分比估计值。构建结束时，工具栏会显示一个**状态标签**，带有编译用时和一个严重程度图标：

- 绿色对勾：编译成功。
- 琥珀色三角形：编译完成但有警告。你仍然会得到 PDF。
- 红色叉号：编译出错。

成功时，预览会自动切换到 PDF。只有真正的失败（没有生成 PDF）才会把你切换到日志视图。

![编译失败后，错误在编辑器和日志中被标出，修复后重新编译成功。](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## 阅读日志

![日志和上次构建的用时位于预览工具栏的左侧。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

预览工具栏左侧的**日志**按钮在 PDF 和编译日志之间切换，上面的徽章会统计错误（红色）或警告（琥珀色）数量：

- 顶部是解析后的**诊断列表**：每个错误或警告都带有类型，已知时还有 `l.42` 这样的行号引用。字体无法显示的字符会归入**缺失的字符**。
- 下面是完整的原始编译器日志，带有着色：错误为粗体红色，行号引用高亮，文件嵌套缩进显示。
- **复制日志**按钮可以把全部内容复制下来，用于提交错误报告或发论坛帖子。在日志中先按 ⌘A 再按 ⌘C 也能复制全部内容。
- **清除**位于**复制日志**旁边，会隐藏日志及其错误，直到下次编译。你的构建文件会保留，下次编译会写入新的日志。

长日志也会立即打开，即使有 100,000 行，滚动时也没有空白区域。

编译错误还会通过 [Linter 流水线](/docs/editor/#the-built-in-latex-linter)在编辑器中显示为波浪线，当你让 [AI 助手](/docs/ai-chat/)修复这些错误时，它也可以用自己的 `get_log` 工具读取同一份日志。

Typst 错误会标记在编辑器中 Typst 报告的确切范围上，并附有源码行和 Typst 自己的提示。常见错误还会附带一段通俗的说明，解释哪里出了问题。

## 宏包与离线编译

Tectonic 在文档第一次需要某个 LaTeX 宏包时下载它，然后在本地缓存。一台电脑上的首次编译还会一次性获取一批常用宏包。这次首次编译可能比较慢，并且需要网络连接。之后的编译会使用缓存。如果 Oleafly 的宏包镜像失败，编译会回退到上游来源，日志里会这样说明。

**设置 → 通用**中或命令面板里的**离线模式**，让 Tectonic 的这一点成为保证。编译器会以 `--only-cached` 运行，从不获取宏包。需要未缓存宏包的文档会失败，提示会尽可能指明缺少的文件，而**关闭并编译**会关闭离线模式并重新编译。

离线模式同样适用于 Typst。开启时 Typst 无法下载宏包，所以每个 `@preview` 包都必须已经在缓存中，或者放在项目的 `typst-packages` 文件夹里。请参阅[来自 Typst Universe 的包](/docs/typst/#packages-from-typst-universe)。Markdown 项目会忽略离线模式，日志里会这样说明。

`latexmk` 使用你机器上已安装的 TeX 发行版。Oleafly 会先检查系统发行版，包括 MacTeX、TeX Live、MiKTeX 和 TinyTeX，**设置 → 引擎 → LaTeX** 会把它用于编译的那个标为**使用中**。如果一个都没有，应用可以安装并管理它自己的 TinyTeX 副本。MiKTeX 还需要 Perl 才能运行 `latexmk`，请参阅 [MiKTeX 与 Perl](/docs/latex-engines/#miktex-and-perl)。由于系统 TeX 进程可以读取你的用户账户可访问的文件，请只对你信任的项目使用 `latexmk`。

当 `latexmk` 构建找不到 `.sty`、`.cls`、参考文献样式、字体文件、babel 语言文件、TikZ 库或其他 TeX 文件时，Oleafly 可以在错误消息中提供**查找并安装**。文件名和宏包名常常不同：例如 `tikz.sty` 属于 TeX Live 宏包 `pgf`。Oleafly 会解析出它属于哪个宏包，用 `tlmgr` 安装，刷新宏包列表，然后重新编译。在 Debian、Ubuntu 和 Fedora 上，TeX Live 由系统的包管理器管理，所以 Oleafly 会给你 `apt` 或 `dnf` 命令。如果你更愿意先搜索或手动管理宏包，请使用**设置 → 引擎 → LaTeX** 中的**宏包**列表。

## 限制与安全阀

- 每个项目同一时间只运行一次编译，使用只保留最新请求的队列：较新的请求会取代过期的请求，所以在构建中途切换项目永远不会绘制出错误的 PDF，你输入时也不会形成编译风暴。
- 被取代或超时的构建会被真正取消：Oleafly 在所有平台上都会终止编译器的整个进程树，而不是让它留在后台继续运行。
- 运行超过 5 分钟的编译会被停止，而不是任由它永远转下去。Tectonic 仍在下载宏包时，每次下载都会把时限往后推，最多共 30 分钟。Markdown 转 PDF 有 15 分钟，Quarto 和 Calepin 有一个小时。
- 结果带有与请求绑定的标识，所以乱序完成产生的过期 PDF 会被拒绝，而不是显示出来。

## 常见故障与快速修复

- **离线模式下出现“缺少宏包”**：在提示中选择**关闭并编译**，或者把离线模式关闭一次编译，以获取并缓存它，然后再把它打开。
- **“此编译器需要一个可用的 TeX 发行版”**：pdfLaTeX 和其他 `latexmk` 编译器需要这台电脑上有 TeX，所以没有 TeX 时选择它们会打开这个对话框。选择**下载并使用 TinyTeX**，或选择**切换回 Tectonic** 回到内置引擎。如果编译已经因此失败，预览会提供**下载并使用 TinyTeX** 和**使用 Tectonic**。请参阅[没有安装 TeX 时](/docs/latex-engines/#when-no-tex-is-installed)。
- **MiKTeX 上出现“latexmk 需要 Perl”**：安装 Strawberry Perl，或安装自带 Perl 的 TinyTeX。请参阅 [MiKTeX 与 Perl](/docs/latex-engines/#miktex-and-perl)。
- **`latexmk` 构建中缺少文件**：使用**查找并安装**。如果查找失败，请在**设置 → 引擎 → LaTeX** 的**宏包**列表中搜索文件名或宏包名。在 Debian、Ubuntu 或 Fedora 上，用 `apt` 或 `dnf` 安装。MiKTeX 宏包在 MiKTeX Console 中管理。
- **未安装 upLaTeX 或 pLaTeX**：提供时选择**安装日文支持（约 450 MB）**，或运行提示中给出的命令。请参阅[日文文档](/docs/latex-engines/#japanese-documents-uplatex-and-platex)。
- **PDF 中缺少文字**，常见于韩文、中文或日文：字体没有这些字符的字形，TeX 会直接略过它们而不报错。Oleafly 会发出警告，日志里附有可以粘贴的设置。请参阅[PDF 中缺失的字符](/docs/latex-engines/#characters-missing-from-the-pdf)，Typst 则参阅[显示为方框的字符](/docs/typst/#characters-that-show-as-boxes)。
- **PDF 中缺少索引、术语表或符号表**：Tectonic 无法运行 `makeindex`。请把项目切换到 `latexmk`，或用 `\makenoidxglossaries` 构建术语表，它不需要外部工具。在 `latexmk` 上，用 `xindy` 或 `\newglossary` 生成的列表不会被构建。
- **编译超时**：再编译一次。如果宏包还在下载，下载会从中断的地方继续。对于 Tectonic 上的长草稿，请把**编译模式**设为**快速**。
- **Tectonic 中的 EPS 图片、被强制使用的 `pdftex` 驱动或缺少的捆绑文件**：引擎对话框会打开。如果没有打开，或者你把它关掉了，请选择**选择引擎**。[当 Tectonic 不够用时](/docs/latex-engines/#when-tectonic-isnt-enough)说明了它在每个视图中的位置。请选择标有**推荐**的方案：Oleafly 找到可用的 TeX 发行版时是你的系统 LaTeX，找不到时是**下载并使用 TinyTeX**。对于缺少的宏包，Oleafly 可以在切换后继续进入它的安装程序。
- **`minted`、PythonTeX 或 `\write18` 被阻止**：如果你信任项目中的每个文件，请选择编辑器上方横幅中的**允许外部命令**。请参阅[允许外部命令](/docs/latex-engines/#allow-external-commands)。
- **Tectonic 中的宏包下载失败**：请检查网络连接，并在提示中选择**重新编译**。Oleafly 在镜像失败后已经试过上游来源，下载会从中断的地方继续，如果电脑当时处于离线状态，网络恢复后编译会自动再运行一次。
- **“Typst 0.13.1 未安装”**：项目固定了这台电脑上没有的 Typst 版本。请在预览中选择**下载 Typst 0.13.1**，或选择**使用 Typst**，后接你的默认版本，以去掉固定。请参阅[当固定的版本缺失时](/docs/typst/#when-a-pinned-version-is-missing)。
- **未定义的引用或交叉引用警告**：[预检](/docs/preflight/#six-independent-checks)会精确指出每一处，附带文件和行号。
- **你无法解读的错误**：问问 AI。“修复 LaTeX 错误”会触发编译、读取日志、定向编辑再重新编译的循环，并使用你选择的[审批策略](/docs/ai-chat/)。

## 其他文档引擎

LaTeX 编译器的选择与项目的文档引擎是分开的：

- **Typst 项目**使用内置的 Typst 0.15.1 或项目固定的版本编译。请参阅 [Typst 项目](/docs/typst/)。
- **Markdown 项目**通过受管理的 Pandoc 构建为 PDF，以 Tectonic 作为 PDF 引擎。
- **Quarto 项目**用 Quarto 渲染 `.qmd` 和 `.Rmd` 文件，输出为 PDF 或网页。请参阅 [Quarto](/docs/engines/#quarto)。
- **Calepin 项目**先用 Calepin 运行 Typst 文档中的代码，再用内置的 Typst 构建 PDF。请参阅 [Calepin](/docs/engines/#calepin)。在你[允许](/docs/engines/#allow-code-in-a-project)之前，这两种引擎都不会运行项目中的代码。
- **带标签的无障碍 PDF** 通过系统 TeX 安装或 Oleafly 托管的 TinyTeX 使用 LuaLaTeX。请参阅 [LaTeX 引擎与宏包](/docs/latex-engines/)。Typst 0.14 及更高版本无需额外步骤，就会给每个 PDF 加上标签。

引擎是创建项目时为每个项目做出的选择，界面会据此调整：引擎无法支持的操作会被隐藏，而不是留着让它失败。要把 LaTeX 项目迁移到 Typst，请[将其转换为新的 Typst 项目](/docs/typst/#convert-a-latex-project-to-typst)。

## 在构建成功后保留源码

启用[检查点](/docs/checkpoints/)，可以保存成功编译所用的源码。你可以比较并恢复较早的构建，而不改变你手动使用 Git 的工作流。

若要把编译出的 PDF 本身也保留在项目文件夹里，请在预览的保存菜单中打开[编译时同步 PDF](/docs/pdf-preview/#sync-pdf-on-compiles)。
