06使用 LaTeX Workshop 编译与预览文档

LaTeX Workshop 负责从 VS Code 调用 LaTeX 工具链、解析日志并预览 PDF，但它不包含 TeX compiler。开始前需要先安装 TeX Live 或 MiKTeX，并确认终端可以找到 latexmk、pdflatex 或 xelatex。

安装扩展并检查工具链

code --install-extension james-yu.latex-workshop
latexmk --version
xelatex --version

工具命令在普通终端中不可用时，先修复 TeX distribution 的安装或 PATH，不要在每一条 VS Code recipe 中写死安装目录。

优先使用 latexmk

LaTeX 文档可能需要多次编译，并在中间调用 BibTeX 或 Biber。latexmk 会根据依赖自动决定需要执行哪些步骤，比手写 pdflatex → bibtex → pdflatex → pdflatex 更容易维护。LaTeX Workshop 默认也提供 latexmk recipe。LaTeX Workshop: Compile

使用 pdfLaTeX 时，默认 recipe 通常已经足够。需要 XeLaTeX 时可以增加一套明确的工具：

{
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk (XeLaTeX)",
      "tools": ["latexmk-xelatex"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk-xelatex",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-xelatex",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ]
    }
  ],
  "latex-workshop.latex.recipe.default": "first"
}

%DOC%、%OUTDIR% 等由 LaTeX Workshop 在运行时替换，因此配置可以跨项目和电脑使用。

不同项目使用不同 engine 时，不必把所有人的用户设置改成 XeLaTeX。可以把 recipe 放进项目 .vscode/settings.json，或者在 root .tex 文件中使用项目已经约定的构建方式。

自动构建不要过于频繁

{
  "latex-workshop.latex.autoBuild.run": "onSave"
}

onSave 适合普通文档：保存后构建一次，不会在每个按键后触发工具链。大型文档、需要外部数据或编译时间较长时，可以关闭自动构建并手动运行 LaTeX Workshop: Build LaTeX project。

自动构建使用 latex-workshop.latex.recipe.default 指定的 recipe。值为 "first" 时使用列表第一项，"lastUsed" 则重复上一次手工选择。

优先使用内置 PDF viewer

{
  "latex-workshop.view.pdf.viewer": "tab"
}

内置 viewer 不需要本机可执行文件路径，支持自动刷新和 SyncTeX，因而比下面这种配置更容易迁移：

{
  "latex-workshop.view.pdf.viewer": "external",
  "latex-workshop.view.pdf.external.viewer.command": "D:/specific/viewer.exe"
}

确实依赖外部阅读器功能时，再把 command 保存在本机用户设置中，不要提交给项目。LaTeX Workshop: View

清理辅助文件

latexmk 已经知道自己生成了哪些中间文件。手动清理时可以继续使用扩展默认的 latexmk clean command，而不必维护一长串扩展名：

{
  "latex-workshop.latex.clean.method": "command",
  "latex-workshop.latex.clean.command": "latexmk",
  "latex-workshop.latex.clean.args": [
    "-outdir=%OUTDIR%",
    "-c",
    "%TEX%"
  ],
  "latex-workshop.latex.autoClean.run": "never"
}

保持 autoClean: "never" 可以留下 .aux、.fls 等供增量构建和 root-file 分析使用。需要清理时运行 LaTeX Workshop: Clean up auxiliary files；不建议每次成功构建后自动删除全部中间文件。

多文件项目先确认 root file

LaTeX Workshop 会从 \documentclass、\input、\include 等关系寻找 root document。无法正确识别时，在子文件开头加入：

% !TEX root = ../main.tex

然后重新运行构建。只有 root 判断正确，recipe、PDF 路径、引用和 SyncTeX 才会指向同一份文档。

{
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk (XeLaTeX)",
      "tools": ["latexmk-xelatex"]
    }
  ],
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk-xelatex",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-xelatex",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ]
    }
  ],
  "latex-workshop.latex.recipe.default": "first",
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.autoClean.run": "never"
}