构建工具

完成一份真正的文档，通常要把 latex 跑两遍，中间还要插入 biber（参考文献）和 makeindex（索引）等命令，并且顺序和次数都要正确。手动重复这些步骤既麻烦又容易出错。构建工具 正是用来自动化这件事的。常见的有三种：能自动判断需要跑几遍的 latexmk，用 TOML 写配置的 llmk，以及把步骤明写在源码中的 arara。

为什么需要构建工具

确定交叉引用和目录至少需要 两次 编译（第一次把编号写入 .aux，第二次再读回正文）。如果有参考文献，中间还要运行 biber 或 bibtex；如果有索引，要运行 makeindex；术语表还会需要别的命令。顺序或次数错了，编号就会不同步。构建工具会把需要的命令按 正确顺序、必要次数 自动运行，并重复到结果稳定为止。各个单独命令的作用请参见“编译命令”。

latexmk — 自动处理的标准工具

latexmk（John Collins 编写的 Perl 脚本）是事实上的标准，Overleaf 默认也使用它。它会观察 .aux 等文件的变化，自行判断是否需要再次运行，并在合适时机调用 biber/bibtex 和 makeindex。它会自动重复直到输出稳定，所以用户基本上只需要说“构建”。

最方便的尤其是 -pvc（preview continuously）：每次保存时，只重新构建必要的部分，并刷新查看器。

latexmk -pdf -pvc document.tex   # 保存のたび自動ビルド / rebuild on every save
latexmk -c                       # 補助ファイルを掃除 / clean aux files

它的行为可以写在 .latexmkrc 配置文件中（当前目录的 latexmkrc/.latexmkrc，或 ~/.latexmkrc）。$pdf_mode 选择输出路线；在当前 latexmk 中，1 表示 pdfLaTeX，2 表示 DVI → dvips → ps2pdf，3 表示 DVI → dvipdf，4 表示 LuaLaTeX，5 表示 XeLaTeX。处理日文时，常见做法是把 $latex 指向 uplatex，把 $dvipdf 指向 dvipdfmx，并用 $pdf_mode = 3 走 DVI 转换生成 PDF。

# .latexmkrc
$pdf_mode = 1;   # 1 = pdflatex
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';

llmk — 随文档携带的配置

llmk（Light LaTeX Make，Takuto Asakura 开发） 是用 TOML 声明式 描述构建流程的工具。可以在 llmk.toml 中写 source（目标文件）和所用命令，也可以把同样的设置嵌入 .tex 中的 魔法注释。它的目标是“无论谁、在哪里执行，都得到同样结果”的可复现性。配置能和文档一起移动，因此适合协作和分发。

# llmk.toml
latex  = "lualatex"
source = "main.tex"

使用魔法注释时，把 TOML 写在由三个以上 + 包围的行之间（也能读取 % !TEX 形式和 YaTeX 形式，但 TOML 块优先）：

% +++
% latex = "uplatex"
% dvipdf = "dvipdfmx"
% +++
\documentclass{ujarticle}

arara — 在源码中明示步骤

arara（Island of TeX，Paulo Cereda 等人开发） 与解析日志来猜测次数的工具相反，是一种 作者明确写出要做什么 的工具。在 .tex 开头用注释列出 指令，运行 arara document.tex 后，它会自上而下执行这些步骤（每一步成功后才进入下一步）。看源码就能一眼知道会运行什么。

% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex: { synctex: yes }
\documentclass{article}

每条指令都对应一个 规则，也就是描述如何调用命令的 YAML 文件。pdflatex 指令映射到 pdflatex 规则，也可以像 { synctex: yes } 那样传递选项。它适合需要完全控制步骤，或需要严格复现特殊流程的场合。

该选哪一个

• latexmk — 自动判断需要的轮数。最普及，-pvc 的实时预览也很舒适。犹豫时选它。
• llmk — 可以把 TOML 配置随文档一起分发，跨环境复现性高。适合协作和发布。
• arara — 在源码中明示步骤。运行内容一目了然，适合需要严格管理流程时。

这三者都比手动输入 (u)platex → dvipdfmx 更安全、更快。拿不准时先从 latexmk -pdf -pvc 开始；等需要可携带的配置或更明确的流程时，再考虑 llmk 或 arara。

构建工具这一章的项目契约

构建工具不只是方便的命令名，而是和协作者及 CI 之间的 项目契约。无论选择 .latexmkrc、llmk.toml 还是 arara 指令，都要把“这份稿件用哪个引擎、用什么工具处理文献、是否生成索引、PDF 输出到哪里”记录在文件中。先写好构建工具这一章的项目契约，即使更换编辑器，也能在提交 PDF 前复现同一流程。

日常运用中，编辑器按钮和 CI 都应该调用同一份契约。如果人手使用 latexmk -pdf main.tex，而 CI 另行直接跑 lualatex，字体或文献处理的失败可能直到提交前才暴露。先确定一个能在命令行成功的命令，再把它分发给编辑器、监视构建和 CI，才更安全。