跳转到内容
Oleaflyv0.4.12

编译 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 的 LaTeXTypstMarkdown
自动编译是是是是
编译模式(常规或快速)是否否否
语法检查是是否否
编译器(本项目)是是否否
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 项目会忽略离线模式,日志里会这样说明。

Tectonic 与 Typst 在哪里找到包Tectonic 先在这台电脑上的包缓存中查找 LaTeX 宏包,缺少的会下载一次。如果你已把包复制到项目中,Typst 会先查看项目的 typst-packages 文件夹,再查看 Oleafly 的包缓存,缺少的包会从 Typst Universe 下载一次。离线模式会关闭这两种下载。在线TectonicTypsttypst-packages在项目中包缓存在这台电脑上包缓存在这台电脑上TeX 宏包只下载一次Typst Universe只下载一次离线模式下不下载Tectonic 与 Typst 在哪里找到包Tectonic 先在这台电脑上的包缓存中查找 LaTeX 宏包,缺少的会下载一次。如果你已把包复制到项目中,Typst 会先查看项目的 typst-packages 文件夹,再查看 Oleafly 的包缓存,缺少的包会从 Typst Universe 下载一次。离线模式会关闭这两种下载。在线TectonicTypsttypst-packages在项目中包缓存在这台电脑上包缓存在这台电脑上TeX 宏包只下载一次Typst Universe只下载一次离线模式下不下载
编译会先在这台电脑上查找。缺少的包只下载一次,除非开启了离线模式。

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。

图片预览

无法加载 AI 回答

请重试,或搜索文档。