编译
编译 LaTeX、Typst 和 Markdown 项目,为每种引擎选择编译选项,阅读日志,并控制离线时的宏包获取。
新的 LaTeX 项目从设置 → 引擎 → LaTeX中的默认编译引擎开始。开箱即用的是 Tectonic,一个基于 XeTeX、随 Oleafly 一起提供的引擎。当项目需要传统的 TeX 工具链时,你也可以使用 latexmk,可以只用于一个项目,也可以设为默认。Typst 项目使用内置的 Typst 或项目固定的其他版本编译,Markdown 项目则经由 Pandoc 和 Tectonic 处理。LaTeX 编译器和 Typst 版本属于项目本身,所以更改一个项目不会影响其他项目。
开始编译
标题为“开始编译”的部分
- ⌘↵(Ctrl+Enter),在任何地方都可以。
- 工具栏右上角的编译按钮。项目有了结果之后,它会显示为重新编译。
- ⌘K 命令面板中的重新编译。
- 将项目打开到显示 PDF 窗格的视图时,会自动编译一次,这样你看到的就是最新的预览。
- 在终端或脚本中运行
oleafly build。参见命令行工具。
编译总是先保存当前文件,所以 PDF 与你看到的内容一致。如果你处于仅编辑器视图,编译会展开分屏视图,让你看到结果。
编译选项
标题为“编译选项”的部分重新编译旁边的箭头会打开编译选项。菜单只显示对项目引擎有作用的选项。
| 分组 | 使用 Tectonic 的 LaTeX | 使用 latexmk 的 LaTeX | Typst | Markdown |
|---|---|---|---|---|
| 自动编译 | 是 | 是 | 是 | 是 |
| 编译模式(常规或快速) | 是 | 否 | 否 | 否 |
| 语法检查 | 是 | 是 | 否 | 否 |
| 编译器(本项目) | 是 | 是 | 否 | 否 |
| Typst 版本、字体、构建、变体 | 否 | 否 | 是 | 否 |
| 编译错误处理 | 是 | 是 | 否 | 否 |
停止编译和从头重新编译位于每种引擎菜单的底部。Typst 项目有了构建变体之后,才会出现变体分组。
在编译器(本项目) 下,Tectonic 是内置的。自动通过 latexmk 运行你的系统 TeX,并根据源码选择编译器。pdfLaTeX、XeLaTeX 和 LuaLaTeX 会固定使用那个编译器,同样通过 latexmk 运行,upLaTeX 和 pLaTeX 用来编译日文文档。除 Tectonic 外,每个选项都需要 TeX 发行版。如果这台电脑上没有,选择它们时 Oleafly 会提议安装 TinyTeX。请参阅没有安装 TeX 时。Typst 的各个分组在 Typst 项目中介绍。
自动编译
标题为“自动编译”的部分在编译选项中把自动编译设为开启,或在 ⌘K 面板中运行启用自动编译。它默认关闭,对所有项目生效,同样的控件也可以再把它关掉。
在 LaTeX 或 Markdown 项目中,Oleafly 会在你停止输入约 2.5 秒后重新编译。只有真正的编辑才会触发它。切换标签页或打开文件不会。
在 Typst 项目中,自动编译就是实时预览。Oleafly 让一个 Typst 进程持续运行,打开的文件会在你停止输入片刻后自动保存,PDF 会在相同的滚动位置刷新。请参阅用自动编译实时预览。
编译不会堆积。如果你在自动编译运行时继续编辑,Oleafly 会停止它,并用你最新的文本重新开始,让 PDF 更快跟上。当编译是你或智能体启动的、正在下载宏包、快要完成,或者它本身就是一次重启时,Oleafly 会让它完成。在这些情况下,只会排队一次后续编译,所以最终的 PDF 仍然反映你最新的编辑。
查看进度
标题为“查看进度”的部分构建期间,预览顶部会有一条细细的进度条,第一份 PDF 出现之前,窗格会显示一个百分比估计值。构建结束时,工具栏会显示一个状态标签,带有编译用时和一个严重程度图标:
- 绿色对勾:编译成功。
- 琥珀色三角形:编译完成但有警告。你仍然会得到 PDF。
- 红色叉号:编译出错。
成功时,预览会自动切换到 PDF。只有真正的失败(没有生成 PDF)才会把你切换到日志视图。

阅读日志
标题为“阅读日志”的部分
预览工具栏左侧的日志按钮在 PDF 和编译日志之间切换,上面的徽章会统计错误(红色)或警告(琥珀色)数量:
- 顶部是解析后的诊断列表:每个错误或警告都带有类型,已知时还有
l.42这样的行号引用。字体无法显示的字符会归入缺失的字符。 - 下面是完整的原始编译器日志,带有着色:错误为粗体红色,行号引用高亮,文件嵌套缩进显示。
- 复制日志按钮可以把全部内容复制下来,用于提交错误报告或发论坛帖子。在日志中先按 ⌘A 再按 ⌘C 也能复制全部内容。
- 清除位于复制日志旁边,会隐藏日志及其错误,直到下次编译。你的构建文件会保留,下次编译会写入新的日志。
长日志也会立即打开,即使有 100,000 行,滚动时也没有空白区域。
编译错误还会通过 Linter 流水线在编辑器中显示为波浪线,当你让 AI 助手修复这些错误时,它也可以用自己的 get_log 工具读取同一份日志。
Typst 错误会标记在编辑器中 Typst 报告的确切范围上,并附有源码行和 Typst 自己的提示。常见错误还会附带一段通俗的说明,解释哪里出了问题。
宏包与离线编译
标题为“宏包与离线编译”的部分Tectonic 在文档第一次需要某个 LaTeX 宏包时下载它,然后在本地缓存。一台电脑上的首次编译还会一次性获取一批常用宏包。这次首次编译可能比较慢,并且需要网络连接。之后的编译会使用缓存。如果 Oleafly 的宏包镜像失败,编译会回退到上游来源,日志里会这样说明。
设置 → 通用中或命令面板里的离线模式,让 Tectonic 的这一点成为保证。编译器会以 --only-cached 运行,从不获取宏包。需要未缓存宏包的文档会失败,提示会尽可能指明缺少的文件,而关闭并编译会关闭离线模式并重新编译。
离线模式同样适用于 Typst。开启时 Typst 无法下载宏包,所以每个 @preview 包都必须已经在缓存中,或者放在项目的 typst-packages 文件夹里。请参阅来自 Typst Universe 的包。Markdown 项目会忽略离线模式,日志里会这样说明。
latexmk 使用你机器上已安装的 TeX 发行版。Oleafly 会先检查系统发行版,包括 MacTeX、TeX Live、MiKTeX 和 TinyTeX,设置 → 引擎 → LaTeX 会把它用于编译的那个标为使用中。如果一个都没有,应用可以安装并管理它自己的 TinyTeX 副本。MiKTeX 还需要 Perl 才能运行 latexmk,请参阅 MiKTeX 与 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 时。 - MiKTeX 上出现“latexmk 需要 Perl”:安装 Strawberry Perl,或安装自带 Perl 的 TinyTeX。请参阅 MiKTeX 与 Perl。
latexmk构建中缺少文件:使用查找并安装。如果查找失败,请在设置 → 引擎 → LaTeX 的宏包列表中搜索文件名或宏包名。在 Debian、Ubuntu 或 Fedora 上,用apt或dnf安装。MiKTeX 宏包在 MiKTeX Console 中管理。- 未安装 upLaTeX 或 pLaTeX:提供时选择安装日文支持(约 450 MB),或运行提示中给出的命令。请参阅日文文档。
- PDF 中缺少文字,常见于韩文、中文或日文:字体没有这些字符的字形,TeX 会直接略过它们而不报错。Oleafly 会发出警告,日志里附有可以粘贴的设置。请参阅PDF 中缺失的字符,Typst 则参阅显示为方框的字符。
- PDF 中缺少索引、术语表或符号表:Tectonic 无法运行
makeindex。请把项目切换到latexmk,或用\makenoidxglossaries构建术语表,它不需要外部工具。在latexmk上,用xindy或\newglossary生成的列表不会被构建。 - 编译超时:再编译一次。如果宏包还在下载,下载会从中断的地方继续。对于 Tectonic 上的长草稿,请把编译模式设为快速。
- Tectonic 中的 EPS 图片、被强制使用的
pdftex驱动或缺少的捆绑文件:引擎对话框会打开。如果没有打开,或者你把它关掉了,请选择选择引擎。当 Tectonic 不够用时说明了它在每个视图中的位置。请选择标有推荐的方案:Oleafly 找到可用的 TeX 发行版时是你的系统 LaTeX,找不到时是下载并使用 TinyTeX。对于缺少的宏包,Oleafly 可以在切换后继续进入它的安装程序。 minted、PythonTeX 或\write18被阻止:如果你信任项目中的每个文件,请选择编辑器上方横幅中的允许外部命令。请参阅允许外部命令。- Tectonic 中的宏包下载失败:请检查网络连接,并在提示中选择重新编译。Oleafly 在镜像失败后已经试过上游来源,下载会从中断的地方继续,如果电脑当时处于离线状态,网络恢复后编译会自动再运行一次。
- “Typst 0.13.1 未安装”:项目固定了这台电脑上没有的 Typst 版本。请在预览中选择下载 Typst 0.13.1,或选择使用 Typst,后接你的默认版本,以去掉固定。请参阅当固定的版本缺失时。
- 未定义的引用或交叉引用警告:预检会精确指出每一处,附带文件和行号。
- 你无法解读的错误:问问 AI。“修复 LaTeX 错误”会触发编译、读取日志、定向编辑再重新编译的循环,并使用你选择的审批策略。
其他文档引擎
标题为“其他文档引擎”的部分LaTeX 编译器的选择与项目的文档引擎是分开的:
- Typst 项目使用内置的 Typst 0.15.1 或项目固定的版本编译。请参阅 Typst 项目。
- Markdown 项目通过受管理的 Pandoc 构建为 PDF,以 Tectonic 作为 PDF 引擎。
- Quarto 项目用 Quarto 渲染
.qmd和.Rmd文件,输出为 PDF 或网页。请参阅 Quarto。 - Calepin 项目先用 Calepin 运行 Typst 文档中的代码,再用内置的 Typst 构建 PDF。请参阅 Calepin。在你允许之前,这两种引擎都不会运行项目中的代码。
- 带标签的无障碍 PDF 通过系统 TeX 安装或 Oleafly 托管的 TinyTeX 使用 LuaLaTeX。请参阅 LaTeX 引擎与宏包。Typst 0.14 及更高版本无需额外步骤,就会给每个 PDF 加上标签。
引擎是创建项目时为每个项目做出的选择,界面会据此调整:引擎无法支持的操作会被隐藏,而不是留着让它失败。要把 LaTeX 项目迁移到 Typst,请将其转换为新的 Typst 项目。
在构建成功后保留源码
标题为“在构建成功后保留源码”的部分启用检查点,可以保存成功编译所用的源码。你可以比较并恢复较早的构建,而不改变你手动使用 Git 的工作流。
若要把编译出的 PDF 本身也保留在项目文件夹里,请在预览的保存菜单中打开编译时同步 PDF。