跳转到内容
Oleaflyv0.4.12

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

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

在你于 设置 → 引擎 → 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。

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

当项目依赖传统的 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。

设置 → 引擎 → 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 发行版的电脑上选择 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 只会改变你自己的电脑。

打开 设置 → 引擎 → 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 的 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,也可以让编译器保持 自动。自动会为 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 引擎做不到的事,例如 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)编译它。

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 目录树中,而且该目录树尚不存在时会先把它建立起来。宏包所在的行会标明它最终的位置。移除一个所属宏包,也会移除它提供的其他文件,所以移除前请阅读 已包含在 说明。

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 分钟,如果放弃,提示会指明它一直在等待的仓库。参见下载源标签页。

在 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 会在文档第一次使用宏包时下载它。

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

模板会声明它们需要的宏包,Tectonic 在第一次编译时获取这些宏包。带有按需字体的模板则单独处理这些字体。参见模板。

图片预览

无法加载 AI 回答

请重试,或搜索文档。