LaTeX 引擎与宏包
选择 Tectonic 或 latexmk 编译器,使用已有的 TeX 发行版,或安装 Oleafly 托管的 TinyTeX。
Oleafly 内置 Tectonic,也可以通过 latexmk 编译。项目的编译器菜单控制日常构建。设置 → 引擎 显示你的电脑上可用的 TeX 发行版和宏包。
Tectonic:日常使用的引擎
标题为“Tectonic:日常使用的引擎”的部分在你于 设置 → 引擎 → LaTeX 的 默认编译引擎 下选择别的引擎之前,Tectonic 就是默认的编译引擎。它不需要单独安装,会按需获取宏包,并把它们缓存起来供离线使用。它适合大多数项目,即使没有安装系统 TeX 发行版,它仍然可用。参见为新项目设置默认值。
要生成 带标签的 PDF,请使用 LuaLaTeX 工作流。标签为辅助技术描述文档结构。编译之后,用预检检查结果。
内置引擎上的字体
标题为“内置引擎上的字体”的部分Tectonic 基于 XeTeX,XeTeX 直接读取字体文件。Oleafly 做了几处调整,让为 pdfLaTeX 编写的文档保留它们的字体和文本:
-
Times、Helvetica、Courier、Palatino、Bookman、New Century Schoolbook 和 Avant Garde 使用它们的 TeX Gyre 版本,而不是回退到 Latin Modern。
-
\usepackage[T1]{fontenc}在这个引擎上会破坏键入的重音符号和符号,所以 Oleafly 让文档保持使用 Unicode 文本。如果文档用到的字体只有 T1 版本,文档就保持使用 T1,编译会警告 ß、§、«、弯引号和 € 等字符可能打印错误或消失。警告里给出了这一行的另一种写法,只在 pdfLaTeX 下加载 T1:\usepackage{iftex}\ifPDFTeX\usepackage[T1]{fontenc}\fi -
按 arXiv 的要求设置了
\pdfoutput=1的文档,会照原样编译。 -
没有设置
fontset的ctex文档会使用 Fandol 字体,所以在每台电脑上看起来都一样。要使用 Mac 自带的字体,请在文档类选项中加入fontset=mac。 -
内置引擎自带的字体按文件名查找。
\setmainfont{UnBatang}会失败,错误信息会告诉你改写成UnBatang.ttf。
离线模式会跳过这些字体和编码调整,所以这类文档的离线构建可能与在线构建看起来不同。
latexmk 与系统 TeX
标题为“latexmk 与系统 TeX”的部分当项目依赖传统的 TeX Live 或 MiKTeX 工作流时,请从项目的编译器菜单中选择 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 或 pLaTeX。Oleafly 通过 latexmk 运行这些编译器。自动 会读取主文件并选出一个:顶部的 % !TeX program = xelatex 行优先,其次是日文文档类,再其次是需要 XeLaTeX 或 LuaLaTeX 的宏包,例如 fontspec、ctex、xeCJK 或 luatexko。如果主文件无法确定,自动还会检查项目中的 latexmkrc 和导言区加载的文件。其余情况都使用 pdfLaTeX。如果某个宏包需要的编译器与自动选出的不同,编译会提议切换,例如 使用 XeLaTeX。
有两种方式可以提供这套工具链:
- 使用现有的安装。 Oleafly 会检测你系统上的 MacTeX、TeX Live、MiKTeX 和 TinyTeX。它会查找与你的终端相同的
PATH,在 Windows 上还会查找系统和用户的Path设置,所以即使应用是从 Dock 或开始菜单打开的,你手动安装的 TeX 也能被找到。只有当系统安装的二进制目录中包含latexmk、pdfLaTeX、XeLaTeX、LuaLaTeX、kpsewhich和 Biber 时,它才会优先于 Oleafly 托管的副本。不完整的安装无法悄悄压过可用的托管 TinyTeX。 - 安装托管的 TinyTeX。 下载大小约 250 MB,不需要管理员权限。请参阅安装和更新 TinyTeX。
设置 → 引擎 → LaTeX 中的 管理 TeX 发行版 会列出 Oleafly 找到的每一个发行版。使用中 标出 latexmk 用于编译的那个,每个可以编译的发行版上还有一个 latexmk 徽章。在另一行上选择 用于编译 即可切换到它。你选择的那一行随后会显示 自动,它让 Oleafly 重新选择:先选完整的系统 TeX,再选 TinyTeX。
如果 TeX 安装在 Oleafly 不会查找的文件夹里,请点击 选择 TeX 文件夹,选取含有 latexmk 的文件夹,或它上一级的 TeX Live 年份文件夹,例如 texlive/2026。Oleafly 会在其中找到 latexmk,并用那份安装来编译,列表会把它标为 使用中。自动 会撤销这个选择。如果该文件夹里没有 latexmk,提示会说明应该改选哪个文件夹。
latexmk 不是文件系统沙箱。即使阻止了 shell 命令,TeX 也能读取你的账户可访问的文件。Oleafly 还会禁用项目、用户和系统级的 .latexmkrc 文件,因为它们是可执行的 Perl 代码。只对你信任的项目使用系统 TeX。导入的项目只有在你选择时才使用系统 TeX,无论是作为默认编译引擎,还是从项目的编译器菜单中选择。就地打开的文件夹在你信任它之前,一直使用 Tectonic。
没有安装 TeX 时
标题为“没有安装 TeX 时”的部分在没有可用 TeX 发行版的电脑上选择 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX、pLaTeX 或自动,会打开一个标题为 此编译器需要一个可用的 TeX 发行版 的对话框。它按以下顺序给出三个选项:
- 下载 TinyTeX,标为 推荐。下载并使用 TinyTeX 会安装 TinyTeX 并用它编译项目。
- 使用我的系统 LaTeX(latexmk),它会说明没有找到 TeX 发行版,或者说明这台电脑上的发行版为什么无法编译。它没有按钮。
- 继续使用 Tectonic。切换回 Tectonic 会让项目回到内置引擎。
如果你先编译,预览会提供同样的出路:下载并使用 TinyTeX、使用 Tectonic 和 打开引擎设置。TinyTeX 仍在下载时开始的编译会等待,安装完成后自动开始。
有 TeX 发行版但没有 latexmk 时,也会出现同样的提议。当发行版缺少 latexmk、所选编译器或 Biber 时,如果 Oleafly 认得该发行版,提示还会指出要安装什么,例如 MacTeX 上的 sudo tlmgr install latexmk,或 Ubuntu 上的 sudo apt install latexmk。
在共享项目中,按钮显示为 为所有人使用 Tectonic,因为编译器保存在项目中,会对每个合作者生效。安装 TinyTeX 只会改变你自己的电脑。
安装和更新 TinyTeX
标题为“安装和更新 TinyTeX”的部分打开 设置 → 引擎 → LaTeX,在 管理 TeX 发行版 下选择 下载 TinyTeX(约 250 MB),或使用编译对话框中的提议。TinyTeX 是精简的 TeX Live,不需要管理员权限。期刊模板之后可能会添加宏包,总共最多约 1 GB,Oleafly 在开始之前会检查是否有约 2 GB 的可用磁盘空间。TinyTeX 安装在 ~/.oleafly/tinytex 下。
- 取消 会停止下载并保留已经到达的部分。按钮随后显示 继续下载,并带有已完成的大小。在安装期间退出 Oleafly 也会以同样方式暂停,下次打开应用时会继续。
- 下载先从 Oleafly 的镜像进行,然后才是 GitHub。如果某个来源失败,或有一分钟不再发送数据,Oleafly 会换到下一个来源,并从中断的地方继续。设置 → 下载 → 下载源 可以更改下载的来源。参见下载源标签页。
- 托管的 TinyTeX 比这个版本的 Oleafly 期望的版本旧时,它所在的行会显示 更新。移除 会删除它。
如果另一个发行版已经是 使用中,安装 TinyTeX 不会切换到它。想让 TinyTeX 来编译时,请在 TinyTeX 所在的行上选择 用于编译。
在 Linux 上,TinyTeX 使用系统的 Perl。Oleafly 在下载任何东西之前会先检查 Perl。如果缺少 Perl 或它的某个标准模块,提示会给出安装命令:sudo apt install perl、sudo dnf install perl 或 sudo pacman -S perl。
在 Windows 上,TeX Live 无法从名称含有带重音符号或非拉丁字母的文件夹中运行。如果你的用户文件夹是这样的名称,Oleafly 会改把 TinyTeX 放在 ProgramData 下的一个文件夹中。如果杀毒软件在 TinyTeX 移入位置时占用了某个文件,Oleafly 会再试一次;如果仍然无法完成,请稍等片刻后重试安装。
MiKTeX 与 Perl
标题为“MiKTeX 与 Perl”的部分MiKTeX 的 latexmk 是一个 Perl 脚本,而 MiKTeX 不包含 Perl。没有 Perl 时,设置会给 MiKTeX 标上 latexmk 需要 Perl,如果已安装 TinyTeX,Oleafly 会改用 TinyTeX 编译。没有其他可用的发行版时,编译会停止,并给出三条出路:从 设置 → 引擎 → LaTeX 安装 TinyTeX(它自带 Perl)、安装 Strawberry Perl,或把项目切回 Tectonic。
MiKTeX 在 MiKTeX Console 中管理它的宏包,所以 宏包 列表和 查找并安装 不适用于它。MiKTeX 编译时也不会转换 EPS 图片,所以请先把它们转换成 PDF,或者改用 TinyTeX。
日文文档:upLaTeX 与 pLaTeX
标题为“日文文档:upLaTeX 与 pLaTeX”的部分日文文档请在 编译器(本项目) 下选择 upLaTeX 或 pLaTeX,也可以让编译器保持 自动。自动会为 jsarticle、jsbook 和 jsreport 选择 pLaTeX(文档类带有 uplatex 选项时选择 upLaTeX),为 uj 系列文档类和 jlreq 选择 upLaTeX,为 ltjsarticle 和其他 LuaTeX-ja 文档选择 LuaLaTeX。
两个编译器都需要 TeX Live 的日文支持。托管的 TinyTeX 或 Oleafly 可以写入的 TeX Live 缺少它时,失败的编译会提供 安装日文支持(约 450 MB),它会安装日文支持并重新编译。在其他安装上,提示会指出适用于你的发行版的命令,例如 sudo apt install texlive-lang-japanese。
Tectonic 不够用时
标题为“Tectonic 不够用时”的部分有些文档需要内置 Tectonic 引擎做不到的事,例如 EPS 图片或强制使用 pdftex 驱动。打开项目后的第一次编译,或你自己启动的编译,遇到这类情况时,引擎对话框会自动打开。由自动编译或代理启动的编译遇到这类情况时,对话框不会打开,而是出现 选择引擎,选择它即可打开对话框。这个按钮会一直保留到下一次编译,所以在你关闭对话框之后,也可以用它再次打开。它出现在哪里取决于视图:
- 编译失败后,当 日志 打开时,它在预览工具栏的右侧。编译没有生成 PDF 时,预览会自动切换到 日志。如果仍在显示 PDF,请选择 日志 来看到这个按钮。
- 在空白预览中,它在 重试编译 旁边。
- 在仅编辑器视图中、PDF 位于单独窗口时,或编译成功之后,它在 重新编译 的左侧。
对话框的标题是 内置引擎无法满足本次编译的需求,并列出它发现的问题。标有 推荐 的选项排在最前面:
- 下载 TinyTeX 在没有安装任何可用的 TeX 发行版时出现。它的按钮 下载并使用 TinyTeX 会安装 TinyTeX,把项目切换到
latexmk,并再次编译。 - 使用我的系统 LaTeX(latexmk) 有 使用系统 LaTeX 按钮,它会把项目切换到
latexmk,使用 Oleafly 找到的 TeX 发行版。如果文档需要 pdfLaTeX,该选项显示为 在我的系统 LaTeX 中使用 pdfLaTeX(latexmk),按钮显示为 切换到 pdfLaTeX 并重新编译。没有安装 TeX 时,这个选项没有按钮。 - 继续使用 Tectonic 有 保留 Tectonic 按钮,它会让项目留在内置引擎上。当切换可以解决对话框列出的问题时,这个选项会说明这些问题不会消失。
保留 Tectonic 之后,同样的问题不会再在这台电脑上为这个项目打开对话框或显示 选择引擎。以后要切换,请在 编译器(本项目) 下选择一个编译器。
如果项目还需要运行外部命令,切换到系统 LaTeX 或 TinyTeX 也会允许它们,对话框会在你点击前说明这一点。你选择的编译器会保存在项目中,所以合作者获得相同的设置。
允许外部命令
标题为“允许外部命令”的部分minted 和 PythonTeX 这样的宏包,以及使用 \write18 的文档,会在编译时运行其他程序。Oleafly 默认阻止这一点。当编译被阻止,或日志显示项目需要这些命令时,编辑器上方的横幅会提供 允许外部命令。
内置引擎同样保持这项阻止。Tectonic 在项目文件夹之外启动,Oleafly 自带的 Biber 会把文档中的参考文献设置当作纯文本,并在编译时跳过 biber.conf。
只对你信任其文件的项目允许外部命令,因为这样 LaTeX 就能以你的权限运行任何程序。这项权限只对系统 LaTeX 生效,并且只保留在这台电脑上。它绝不会存入 project.json 或提交到 Git,所以合著者需要在自己的电脑上单独允许。在共享项目中,Oleafly 会在你打开它之前发出警告,因为任何能编辑该项目的人,都可能在你编译时在你的电脑上运行程序。把项目切回 Tectonic 或删除项目,都会移除这项权限。在就地打开的文件夹中,请先信任该文件夹。信任文件夹本身并不会允许外部命令。
当有可用的引擎时,预检面板中的 编译带标签版本并验证 按钮可以用 LuaLaTeX 生成带标签的 PDF,并立即一步完成审核。更想用自己的工具链?预检的 准备无障碍导出 会为添加标签而重写你的源码,然后你在应用之外用任意 LuaLaTeX(来自 TeX Live 2026,或 2025 年 11 月之后更新过的 TeX Live)编译它。
PDF 中缺失的字符
标题为“PDF 中缺失的字符”的部分TeX 会略去其字体没有字形的任何字符,而编译仍然成功。一段韩文、中文或日文可能变成空白而没有任何错误。Oleafly 在每次编译后都会读取日志,所以字符缺失时,每个项目会收到一次通知,日志会把它们列在 缺失的字符 下,警告里也会点出其中几个。
在内置引擎和 XeLaTeX 上,警告还会为它发现的每种文字给出一套设置,用的是内置引擎自带的字体。把你需要的那一套粘贴到导言区:
% Korean\usepackage[space]{xeCJK}\setCJKmainfont[AutoFakeBold]{UnBatang.ttf}
% Simplified Chinese\usepackage{xeCJK}\setCJKmainfont[AutoFakeBold]{gbsn00lp.ttf}
% Traditional Chinese\usepackage{xeCJK}\setCJKmainfont[AutoFakeBold]{bsmi00lp.ttf}
% Japanese\usepackage{xeCJK}\setCJKmainfont{ipaexm.ttf}[BoldFont=ipaexg.ttf]space 选项会保留韩文单词之间的空格,普通的 xeCJK 会丢掉这些空格。
CJKutf8 和 CJK 宏包只能在 pdfLaTeX 上使用。在内置引擎上加载它们的项目,编译出来的 PDF 没有其中的中文、日文或韩文,所以通知会提供 选择引擎,它会打开切换到 pdfLaTeX 的选项。你也可以删除该宏包及其 CJK 环境,改用上面的某一套设置。
在 Mac 上使用 Mac 自带字体的 ctex 文档,可能会让 macOS 询问是否下载字体,编译会等待你的回答。请回应该对话框后重新编译,或在 \documentclass 的选项中加入 fontset=fandol。
其他缺失的字符,例如符号或另一种文字的字母,需要一个包含它们的字体。请在导言区换成这样的字体。Typst 项目请参阅显示为方框的字符。
宏包管理器
标题为“宏包管理器”的部分引擎状态下方是为 LuaLaTeX 一侧准备的、可筛选的 宏包 列表,由 tlmgr 驱动:
- 从推荐的宏包列表开始,或者至少输入两个字符并选择 搜索 TeX Live 来查询完整目录。
- 按宏包名称或其中包含的文件搜索。当两者名称不同时,Oleafly 会显示拥有该文件的 TeX Live 宏包。
- 一键 添加 或 移除 宏包。已安装的行会显示该宏包位于系统目录树、你的个人目录树,还是两者都有。
- 无障碍导出之前,请查看标签徽章:标记:注意 表示可能降低标签质量的宏包,而 破坏标记 表示已知的冲突。
这个宏包管理器适用于 latexmk 使用的 TeX Live 和 TinyTeX 发行版。Tectonic 管理自己的宏包缓存。对于 MiKTeX,请使用 MiKTeX Console。
缺少文件时的恢复
标题为“缺少文件时的恢复”的部分宏包的名称并不总是与编译日志中提到的文件同名。例如,tikz.sty 是由 pgf 宏包安装的。安装一个猜测出来的名为 tikz 的宏包会失败。
当 latexmk 编译报告缺少文件时,请使用提示中的 查找并安装。它涵盖宏包、文档类、参考文献样式、字体文件、babel 语言文件和 TikZ 库。Oleafly 会询问 TeX Live 哪个宏包拥有该文件,安装该宏包,然后重新编译。如果没有任何 TeX Live 宏包包含该文件,它多半来自你所在大学或出版商的模板,请从原始模板把它添加到项目中。如果有多个宏包包含它,提示会列出这些宏包,让你选出模板需要的那个。如果无法连接目录,或安装没有解决编译问题,提示会说明是哪种情况。
如果你试图在没有权限的情况下改动系统安装,Oleafly 可以改为安装到你的个人 TeX 目录树中,而且该目录树尚不存在时会先把它建立起来。宏包所在的行会标明它最终的位置。移除一个所属宏包,也会移除它提供的其他文件,所以移除前请阅读 已包含在 说明。
让 tlmgr 和旧版 TeX Live 保持可用
标题为“让 tlmgr 和旧版 TeX Live 保持可用”的部分TeX Live 的包管理器 tlmgr 可能落后于在线的 TeX Live 仓库,此后它会拒绝安装任何东西,直到更新自己。对于 Oleafly 托管的 TinyTeX,Oleafly 会更新 tlmgr 并重复安装。对于你自己安装的 TeX Live 或 TinyTeX,提示会让你运行 tlmgr update --self。
仓库换到新的 TeX Live 年份之后,较旧的安装就无法从中安装了。这时 Oleafly 会从你所用版本的最终归档中安装。如果归档里也没有这个宏包,提示会请你更新 TeX Live,或在设置中对托管的 TinyTeX 使用 更新。
选择宏包的来源
标题为“选择宏包的来源”的部分tlmgr 从 TeX Live 仓库安装宏包。Oleafly 托管的 TinyTeX 使用最近的 CTAN 镜像,除非你在 设置 → 下载 → 下载源 的 TeX 宏包仓库 下选择了某个指定的仓库,例如你所在大学的 CTAN 镜像。你自己安装的 TeX Live 会沿用它自己的仓库,除非你在那里输入了地址。Oleafly 每次运行时都会把这个地址交给 tlmgr,绝不会更改它保存的配置。
在网速较慢时,需要访问仓库的宏包搜索可能要花一阵子。Oleafly 最多等待 10 分钟,如果放弃,提示会指明它一直在等待的仓库。参见下载源标签页。
Linux 发行版自带的 TeX Live
标题为“Linux 发行版自带的 TeX Live”的部分在 Debian、Ubuntu 和 Fedora 上,TeX Live 来自系统的包管理器,所以 Oleafly 不会向它添加宏包。宏包 列表会说明要使用 apt 或 dnf,缺少文件时会得到带提示的通知,而不是 查找并安装:
- 在 Debian 和 Ubuntu 上,用
apt-file search加文件名找到宏包,或用sudo apt install texlive-full安装全部内容。 - 在 Fedora 上,通知会针对缺少的文件给出
sudo dnf install 'tex(file.sty)'命令。
当该发行版的 TeX 不完整时,通知还会提供 下载 TinyTeX(约 250 MB),Oleafly 可以为它管理宏包。在 Debian 和 Ubuntu 上,如果你已用 tlmgr init-usertree 建好个人目录树,Oleafly 会把宏包安装到那个目录树中。
从编辑器添加宏包
标题为“从编辑器添加宏包”的部分选择 LaTeX 宏包(LaTeX 编辑器工具栏上的宏包图标),即可不离开文档就搜索 CTAN。每条结果会显示文档是否已经加载它(已在文档中)。在 latexmk 项目中,它还会显示你的 TeX 发行版是否有它(已安装),而 安装 会用 tlmgr 添加缺少的宏包。对于 Linux 发行版自带的 TeX Live,对话框会让你改用 apt 或 dnf 安装宏包。
添加到导言区 会把 \usepackage 这一行写入导言区。选项 让你先添加宏包选项,复制此行 则改为复制这一行。Tectonic 项目没有需要安装的东西:Tectonic 会在文档第一次使用宏包时下载它。
我的 PDF 是用哪个引擎编译的?
标题为“我的 PDF 是用哪个引擎编译的?”的部分- 编译菜单(重新编译 旁边的箭头)中的 编译器(本项目) 会显示当前项目保存的编译器。
- Tectonic 构建使用内置的引擎。
- pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 和 pLaTeX 构建使用
latexmk和设置中标为 使用中 的 TeX 发行版。 - 预检的带标签导出使用 LuaLaTeX,并写入常规的构建位置。
模板与宏包
标题为“模板与宏包”的部分模板会声明它们需要的宏包,Tectonic 在第一次编译时获取这些宏包。带有按需字体的模板则单独处理这些字体。参见模板。