# LaTeX 引擎与宏包

选择 Tectonic 或 latexmk 编译器，使用已有的 TeX 发行版，或安装 Oleafly 托管的 TinyTeX。

Oleafly 内置 Tectonic，也可以通过 `latexmk` 编译。项目的编译器菜单控制日常构建。**设置 → 引擎** 显示你的电脑上可用的 TeX 发行版和宏包。

## Tectonic：日常使用的引擎

在你于 **设置 → 引擎 → LaTeX** 的 **默认编译引擎** 下选择别的引擎之前，**Tectonic** 就是默认的编译引擎。它不需要单独安装，会按需获取宏包，并把它们缓存起来供离线使用。它适合大多数项目，即使没有安装系统 TeX 发行版，它仍然可用。参见[为新项目设置默认值](/docs/engines/#set-a-default-for-new-projects)。

要生成 **带标签的 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：

  ```latex
  \usepackage{iftex}
  \ifPDFTeX
    \usepackage[T1]{fontenc}
  \fi
  ```

- 按 arXiv 的要求设置了 `\pdfoutput=1` 的文档，会照原样编译。
- 没有设置 `fontset` 的 `ctex` 文档会使用 Fandol 字体，所以在每台电脑上看起来都一样。要使用 Mac 自带的字体，请在文档类选项中加入 `fontset=mac`。
- 内置引擎自带的字体按文件名查找。`\setmainfont{UnBatang}` 会失败，错误信息会告诉你改写成 `UnBatang.ttf`。

离线模式会跳过这些字体和编码调整，所以这类文档的离线构建可能与在线构建看起来不同。

## latexmk 与系统 TeX

当项目依赖传统的 TeX Live 或 MiKTeX 工作流时，请从项目的编译器菜单中选择 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 或 pLaTeX。Oleafly 通过 `latexmk` 运行这些编译器。**自动** 会读取主文件并选出一个：顶部的 `% !TeX program = xelatex` 行优先，其次是日文文档类，再其次是需要 XeLaTeX 或 LuaLaTeX 的宏包，例如 `fontspec`、`ctex`、`xeCJK` 或 `luatexko`。如果主文件无法确定，自动还会检查项目中的 `latexmkrc` 和导言区加载的文件。其余情况都使用 pdfLaTeX。如果某个宏包需要的编译器与自动选出的不同，编译会提议切换，例如 **使用 XeLaTeX**。

有两种方式可以提供这套工具链：

1. **使用现有的安装。** Oleafly 会检测你系统上的 MacTeX、TeX Live、MiKTeX 和 TinyTeX。它会查找与你的终端相同的 `PATH`，在 Windows 上还会查找系统和用户的 `Path` 设置，所以即使应用是从 Dock 或开始菜单打开的，你手动安装的 TeX 也能被找到。只有当系统安装的二进制目录中包含 `latexmk`、pdfLaTeX、XeLaTeX、LuaLaTeX、`kpsewhich` 和 Biber 时，它才会优先于 Oleafly 托管的副本。不完整的安装无法悄悄压过可用的托管 TinyTeX。
2. **安装托管的 TinyTeX。** 下载大小约 250 MB，不需要管理员权限。请参阅[安装和更新 TinyTeX](#install-and-update-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 发行版的电脑上选择 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

打开 **设置 → 引擎 → LaTeX**，在 **管理 TeX 发行版** 下选择 **下载 TinyTeX（约 250 MB）**，或使用编译对话框中的提议。TinyTeX 是精简的 TeX Live，不需要管理员权限。期刊模板之后可能会添加宏包，总共最多约 1 GB，Oleafly 在开始之前会检查是否有约 2 GB 的可用磁盘空间。TinyTeX 安装在 `~/.oleafly/tinytex` 下。

- **取消** 会停止下载并保留已经到达的部分。按钮随后显示 **继续下载**，并带有已完成的大小。在安装期间退出 Oleafly 也会以同样方式暂停，下次打开应用时会继续。
- 下载先从 Oleafly 的镜像进行，然后才是 GitHub。如果某个来源失败，或有一分钟不再发送数据，Oleafly 会换到下一个来源，并从中断的地方继续。**设置 → 下载 → 下载源** 可以更改下载的来源。参见[下载源标签页](/docs/settings/downloads/#sources-tab)。
- 托管的 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 的 `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**，也可以让编译器保持 **自动**。自动会为 `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 引擎做不到的事，例如 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，所以合著者需要在自己的电脑上单独允许。在[共享项目](/docs/collaboration/)中，Oleafly 会在你打开它之前发出警告，因为任何能编辑该项目的人，都可能在你编译时在你的电脑上运行程序。把项目切回 Tectonic 或删除项目，都会移除这项权限。在就地打开的文件夹中，请先信任该文件夹。信任文件夹本身并不会允许外部命令。

当有可用的引擎时，[预检](/docs/preflight/)面板中的 **编译带标签版本并验证** 按钮可以用 LuaLaTeX 生成带标签的 PDF，并立即一步完成审核。更想用自己的工具链？预检的 **准备无障碍导出** 会为添加标签而重写你的源码，然后你在应用之外用任意 LuaLaTeX（来自 TeX Live 2026，或 2025 年 11 月之后更新过的 TeX Live）编译它。

## PDF 中缺失的字符

TeX 会略去其字体没有字形的任何字符，而编译仍然成功。一段韩文、中文或日文可能变成空白而没有任何错误。Oleafly 在每次编译后都会读取日志，所以字符缺失时，每个项目会收到一次通知，日志会把它们列在 **缺失的字符** 下，警告里也会点出其中几个。

在内置引擎和 XeLaTeX 上，警告还会为它发现的每种文字给出一套设置，用的是内置引擎自带的字体。把你需要的那一套粘贴到导言区：

```latex
% 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 项目请参阅[显示为方框的字符](/docs/typst/#characters-that-show-as-boxes)。

## 宏包管理器

引擎状态下方是为 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 保持可用

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 分钟，如果放弃，提示会指明它一直在等待的仓库。参见[下载源标签页](/docs/settings/downloads/#sources-tab)。

### 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 是用哪个引擎编译的？

- 编译菜单（**重新编译** 旁边的箭头）中的 **编译器（本项目）** 会显示当前项目保存的编译器。
- Tectonic 构建使用内置的引擎。
- pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 和 pLaTeX 构建使用 `latexmk` 和设置中标为 **使用中** 的 TeX 发行版。
- 预检的带标签导出使用 LuaLaTeX，并写入常规的构建位置。

## 模板与宏包

模板会声明它们需要的宏包，Tectonic 在第一次编译时获取这些宏包。带有按需字体的模板则单独处理这些字体。参见[模板](/docs/templates/#on-demand-fonts-the-setup-badge)。
