自动构建

手动构建 LaTeX 文档意味着反复执行“编译 → 文献 → 编译 → 编译”,还要记住什么时候该重新运行哪一步。自动构建 把这个判断交给工具:它会跟踪依赖,只运行需要的步骤,并且在监视模式下 保存的瞬间就重新构建。本页讨论的是这种工作流程(工具本身的用法见“Build tools”)。

什么是自动构建

有交叉引用、目录、参考文献或索引时,编译需要多次通过,中间还要穿插 bibermakeindex。自动构建工具会 自行判断顺序和次数,在合适的时机调用辅助工具,并一直运行到输出稳定。你实际只需要输入一个命令。标准工具是 latexmk;声明式的替代选择是 llmk

用 latexmk 自动化

只要运行一次 latexmk -pdf document.tex,它就会按需要执行多次编译,调用 bibtex/bibermakeindex,并重复到结果稳定。项目专用设置可以放在 .latexmkrc 中(更换引擎、日语的 uplatex + dvipdfmx 配置等)。协作时,把这个文件提交到仓库,并把它作为项目约定:“本文档用这个命令构建。” 这样在不同编辑器和操作系统上也更容易复现同一个 PDF。各个选项的细节见“Build tools”。

terminal
latexmk -pdf document.tex   # 必要な手順を自動で回す / runs all the needed steps

首先要决定的是“用哪条引擎路径生成 PDF”。只有英文的短文档通常用 pdflatex 就够了;如果有日语文本或 OpenType 字体,通常会选择 upLaTeX + dvipdfmx 或 LuaLaTeX。把这个决定写进 .latexmkrc,编辑器按钮、终端和 CI 就会走同一条路径。文档越长,这种 固定的构建路径 越有价值。

terminal
# .latexmkrc — upLaTeX + dvipdfmx の例 / example route
$latex = 'uplatex -interaction=nonstopmode -halt-on-error %O %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;

每次保存都重新构建 — latexmk -pvc

写作时最方便的模式是 -pvc(preview continuously)。latexmk 会监视 它依赖的所有源文件:主文件,以及通过 \input/\include 引入的 .tex 和图像文件。只要其中任何一个被保存,它就会自动重新构建并刷新查看器。它像文档版的“开发服务器”:保存后立刻看到结果。

terminal
latexmk -pdf -pvc document.tex   # 監視して保存ごとに自動更新 / watch and auto-rebuild on save

只处理变化部分 — 增量构建

latexmk 能避免多余的重跑,是因为它 记录依赖关系。每次运行后,它会把每个源文件的状态保存到名为 .fdb_latexmk 的数据库中,并使用 -recorder 生成的 .fls 文件(列出本次读写的文件)准确掌握涉及的输入和输出。下一次调用时,某个步骤 只有在输入变化时才会重新执行:如果什么都没改,就什么都不会发生;小改动也只触发必要的通过。这就是重新构建很快的原因。

llmk 同样可以自动化构建。因为它的设置以 声明式 写在 llmk.toml 中(或写成文档内的 magic comments),无论谁在什么环境运行,步骤都相同,重现性很好,适合协作和发布。可以这样区分:latexmk 是从日志和依赖关系推断需要重跑哪些步骤的工具,而 llmk 是在文档项目自身明确写出处理流程的工具。

纳入你的工作流程

-pvc 用于写作,普通的 latexmk 运行为提交前检查,latexmk -C 则是清理,用来证明你没有依赖过期的生成文件。尤其在协作中,无法干净构建的文档很可能也会在别人的环境中出问题。不要只依赖保存时的即时预览;在关键节点定期清理并重新构建,最终提交 PDF 时就不会手忙脚乱。

  • 写作时latexmk -pdf -pvc:每次保存自动更新。
  • 随项目附带配置 → 将 .latexmkrc / llmk.toml 放进仓库,确保可重现。
  • 发布前的最后一轮 → 用 latexmk -C 清除输出,然后做一次 clean build。
  • 在服务器或 CI 上构建 → 见“CI”页面。