Sublime Text (LaTeXTools)

要在 Sublime Text 中写入 LaTeX，标准选择是 LaTeXTools 包。从 Package Control 安装它，您将获得构建系统、\ref/\cite 补全、命令补全、文件名补全以及使用 PDF 查看器的双向跳转 - 所有这些都无需离开编辑器。本页介绍了 LaTeXTools 的安装和配置、构建的工作原理、日语配置、补全以及通过 SyncTeX 的正向/反向搜索。

LaTeXTools 是什么

Sublime Text 本身不排版 TeX；实际编译是通过您计算机上的 TeX 安装 完成的 - TeX Live、MacTeX 或 MiKTeX。 LaTeXTools 是连接两者的包。当您编辑 .tex 文件时，它会自动启用构建命令、解析出现错误的日志、上下文感知完成、跳转到 \labels 和引用键的定义，以及启动/同步您的 PDF 查看器。 LaTeXTools 本身不会产生任何结果：它假设本地 TeX 发行版和 PDF 查看器。

需要两个外部部件。首先，一个TeX分布：macOS上的MacTeX（较轻的BasicTeX也可以工作，但您必须单独添加latexmk - 见下文）； MiKTeX 或 TeX Live on Windows； TeX Live 来自 Linux 上的 TUG。其次，PDF 查看器：为了启用正向和反向搜索，LaTeXTools 假定每个平台都有一个默认查看器。

安装通过 Package Control（推荐方法）进行。如果您还没有 Package Control，请先安装它；然后打开命令面板（Windows/Linux 上为 Ctrl+Shift+P，macOS 上为 Cmd+Shift+P），选择“包控制：安装包”，然后从列表中选择 LaTeXTools。无需重新启动：打开 .tex 文件，语法切换到 LaTeX，并且功能将生效。

之后要做两件事。首先，准备一个设置文件：从命令面板运行 LaTeXTools：将用户设置重置为默认，或使用 Preferences |套餐 Settings | LaTeXTools | Settings – 用户，在 User 目录中创建可编辑的 LaTeXTools.sublime-settings（切勿编辑插件文件夹中的默认文件 - 升级时会覆盖该文件）。其次，验证设置： LaTeXTools：检查系统 检查是否可以从 LaTeXTools 访问 TeX 命令和查看器。当某些东西不起作用时，这是要运行的第一个命令。

建筑

构建在 Sublime Text 的标准密钥 Ctrl+B 上运行（Cmd+B 在 macOS 上）。对于一次构建，默认构建器 (traditional) 会执行以下所有操作：保存当前文件，调用 TeX 构建命令，解析日志并在底部面板中列出错误、警告和（如果启用）坏框，然后打开 PDF 查看器并对光标进行正向搜索。单击面板中的错误可跳转到相应行。

关键事实是 traditional 构建器在后台运行 latexmk。 准确地说：它在 TeX Live 和 MacTeX 上调用 latexmk，在 MiKTeX 上调用 texify。 latexmk 找出发生了什么变化，并根据需要多次重新运行工具链，处理重复，直到交叉引用和目录稳定下来。它的默认命令行大致是：

latexmk -cd -f -%E -interaction=nonstopmode -synctex=1

读取：-cd 在处理之前更改为源目录；即使发生错误，-f 也会尽可能地继续前进； -interaction=nonstopmode 避免交互式停止； -synctex=1 发出下面的正向/反向搜索所需的同步数据。 %E 是一个 占位符，根据所选引擎，LaTeXTools 将其替换为 -pdf (pdfLaTeX)、-lualatex、-xelatex 等 - 因此引擎选择相当于交换 %E 扩展的内容。

选择引擎的最简单方法是文件顶部的神奇注释。将其放在 .tex 的第一行，然后使用匹配引擎（没有它，pdfLaTeX）。在多文件项目中，此行位于根（主）文件中。为了实现 TeXShop 兼容性，TS-program 可以代替 program：

%!TEX program = lualatex

仅接受三个值：pdflatex、lualatex 和 xelatex。同样，%!TEX options = ... 将选项传递给引擎（例如 --shell-escape），%!TEX root = <master> 命名根文件。您也可以在设置文件或 Sublime 项目中配置这些注释，而不是魔术注释。在 LaTeXTools.sublime-settings 的 builder_settings 块中，您可以调整 program（引擎）、options、command 和 env（环境变量）：

{
  "builder_settings": {
    "program": "lualatex",
    "options": ["--shell-escape"]
  }
}

另一个重要的是 texpath 设置 - PATH 用于在调用 latexmk 和朋友时查找 LaTeX 命令。特别是在 macOS 上，从 GUI 启动的 Sublime Text 具有与您的 shell 不同的 PATH，因此错误的值会失败并显示“未找到命令”。规则：texpath 必须包含 $PATH （首先是您自己的路径，然后是 $PATH）。典型的 macOS 值为 "/Library/TeX/texbin:$PATH"；在 Windows 上，类似 "C:\\texlive\\2026\\bin\\windows;$PATH"，根据您的安装进行调整。在 Windows 上，还将 distro 设置为 "texlive" 或 "miktex" 以匹配您的发行版。

如果 traditional 还不够，则 builder 设置可让您切换到 basic（运行引擎的最小构建器加上 bibtex/biber）或 script（高级构建器，您可以在 script_commands 中编写自己的命令序列）。请注意，--output-directory、--aux-directory 和 --jobname 仅适用于 latexmk（OS X/Linux 上的 traditional 构建器）、basic 或 script — 它们会被 MiKTeX 的 texify 忽略。

配置日语

这是日本用户经常犯错的地方。 %!TEX program 仅接受 pdflatex、lualatex 和 xelatex — 您不能直接命名 uplatex 或 platex。如果您使用 LuaLaTeX 排版日语，则很简单：编写 %!TEX program = lualatex 并使用 luatexja/ltjsclasses-family 类。

另一方面，要使用 upLaTeX + dvipdfmx — 科学中经典的日本论文组合，它构建一个 DVI，然后将其转换为 PDF — 最简洁的方法是 让 .latexmkrc 选择引擎。 由于 traditional 构建器在后台调用 latexmk，因此将 .latexmkrc 放在项目目录（或您的主目录）将工具链切换为日语处理，几乎不更改 LaTeXTools 自己的设置。这是一个 upLaTeX + dvipdfmx 示例：

$latex = 'uplatex -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
$max_repeat = 5;

关键点：将uplatex赋值给$latex，将dvipdfmx赋值给$dvipdf，然后设置$pdf_mode = 3选择“构建一个DVI，然后用dvipdfmx转换为PDF”路径。将 -synctex=1 传递给 $latex 也会将 SyncTeX 数据传递到 PDF，甚至通过 DVI，因此下面的搜索有效。在 LaTeXTools 方面，最安全的不是编写 %!TEX program 行（这样做会选择 pdfLaTeX %E）。

更明确地说，您可以直接通过 builder_settings 中的 command 键命名 latexmk。编写 "command": "latexmk"（在 .latexmkrc 中保留 -pdfdvi 等选项）可保证日语配置的 latexmk 运行。自定义 command 确实会禁用通过 %!TEX program 的引擎自动选择，但在修复 .latexmkrc 中的工具链的设置中（就像日本工作流程一样），这没有损失。

完成

LaTeXTools 的补全分为三个系列：命令补全、\ref/\cite 补全和文件/包名称补全（填充助手）。首先，命令完成。 LaTeXTools 附带 TeXStudio-derived 补全单词列表 (CWL)，并在您使用 \ 启动命令时立即显示候选弹出窗口。例如，输入 \te，就会出现 \textit 等。该行为由 command_completion 设置控制 - prefixed（默认；仅当单词以 \ 开头时）、always 或 never。文档中加载的包的候选者会通过 cwl_autoload 自动添加（默认情况下处于打开状态）。启用 env_auto_trigger，并且当您键入 \begin{/\end{ 时，环境名称也会完成。

接下来，参考和引用完成——LaTeXTools 的亮点之一。默认情况下，在您输入 \ref{ 或 \cite{ 的瞬间，屏幕顶部会出现一个快速面板（候选列表）：对于 \ref{，文档中的所有 \label；对于 \cite{，您通过 \bibliography{} 或 biblatex 的 \addbibresource{} 引用的参考书目中的所有条目。输入几个字符进行模糊过滤，选择并按 Enter 键，整个命令将被插入，例如\ref{my-label}。在右大括号之前键入一个逗号，如 \cite{paper1,，然后以相同的方式选择 多重引用 的第二个和后面的键。

两个警告。首先，LaTeXTools从保存的文件中收集候选者；如果您刚刚添加的标签或键未显示，请先保存。其次，仅支持 外部 .bib 文件 - 不支持内联写入的 \bibitem 文件。如果这种自动触发感觉有干扰，可以通过切换或设置将其关闭。要手动调用它，请在 \ref{ 等之后按 Ctrl+l, x （Cmd+l, x on macOS）或 Ctrl+l, Ctrl+f （与下面的填充助手相同的键，也适用于 \ref/\cite）。来自 smartef、fancyref、varioref、natbib 和 biblatex 的参考和引文命令也能被识别。

第三个是填充助手。键入 \usepackage{、\include{、\input{、\includegraphics{ 等，它会提供可用包或文件的列表：\usepackage{ 的已安装包，以及文件命令的当前目录中的文件（过滤为 \includegraphics 的图像文件）。默认情况下也会自动显示，或者使用 Ctrl+l, Ctrl+f 手动调用。准备工作之一是包完成：从命令面板运行 LaTeXTools：为 LaTeX 包构建缓存一次以构建包缓存。

SyncTeX（正向/反向搜索）

SyncTeX 记录源代码行和 PDF 中的位置之间的对应关系，从而启用正向搜索（从编辑位置跳转到 PDF）和 反向搜索（从 PDF 中的某个位置返回到源代码行）。 LaTeXTools 的默认构建命令包括 -synctex=1，因此普通的 Ctrl+B 构建会为您发出同步数据 (.synctex.gz)。对于通过 DVI 的日语，重点是将 -synctex=1 传递到 .latexmkrc 中的 $latex，如上所述。 SyncTeX 页面介绍了其工作原理的背景。

正向搜索从 LaTeXTools 键运行。编辑 .tex 时，按 Ctrl+l, j（macOS 上的 Cmd+l, j），然后显示与光标匹配的 PDF 页面。前向搜索也会在构建后立即自动运行，因此 Ctrl+B 单独打开正确的位置。 （Ctrl+l 通常是“将选择扩展到行”，但对于 LaTeXTools 处于活动状态的 .tex 文件，它会重新映射到 Ctrl+l, Ctrl+l，从而释放 Ctrl+l 作为插件命令的前缀。）要仅打开 PDF 而不同步，请使用 Ctrl+l, v。

反向搜索（PDF → 源）需要查看器回调到 Sublime Text。每个观看者的点击手势都不同：

• Skim (macOS) — Cmd+Shift+click 在 PDF 中。
• SumatraPDF (Windows) — 在 PDF 中双击。
• Evince (Linux) — PDF 中的 Ctrl+左键单击（Okular：Shift+左键单击；Zathura：Ctrl+左键单击）。

在 macOS — Skim 上，在 Skim 的首选项中启用反向搜索：打开 首选项 → 同步 选项卡，取消选中“检查文件更改”，然后只需选择 “Sublime Text”预设。在没有预设的旧版 Skim 上，选择“自定义”并将命令设置为 subl (/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl) 的绝对路径，将参数设置为 "%file":%line。

在 Windows — SumatraPDF 上，首先将 SumatraPDF 添加到您的 PATH 中，以便 LaTeXTools 可以轻松找到它。反向搜索设置 UI 仅在您打开具有同步数据 (.synctex.gz) 的 PDF 时出现，因此使用 Ctrl+B 构建一次，在苏门答腊岛打开 PDF，并在 Settings → 选项 下注册下面的反向搜索命令行（调整安装的 ST 路径）：

"C:\\Program Files\\Sublime Text\\sublime_text.exe" "%f:%l"

对于缺乏支持的查看器，前向搜索键 (Ctrl+l, j) 的行为就像“打开 PDF”。当反向搜索出现问题时，请按以下顺序检查：构建是否使用 -synctex=1 运行、查看器的预设/命令是否正确，以及 - 通过 LaTeXTools: Check System - sublime_executable（subl 的位置）是否可见。

第一遍 LaTeXTools 检查

• 首先检查：运行 LaTeXTools: Check System 并确认 TeX 命令、PDF 查看器和 subl 可执行文件可见。
• 日文文档决定： 使用 program = lualatex 代替 LuaLaTeX；对于 upLaTeX，省略 %!TEX program 并将路由放入 .latexmkrc。
• 失败时： 如果 Ctrl+B 表示缺少命令，请检查 texpath；如果引用未更新，请保存并重建；如果 PDF-to-source 失败，请检查查看器反向搜索设置。
• 何时将其设为项目： 一旦图形或章节文件增加，请使用 Sublime 项目或 %!TEX root 固定母版，以便任何选项卡中的 Ctrl+B 都指向相同的 PDF。