VS Code (LaTeX Workshop)

将 LaTeX Workshop 扩展添加到 Visual Studio Code 中，通用代码编辑器将成为一个严肃的 LaTeX 环境：它在每次保存时进行编译，在并排选项卡中显示 PDF，并允许您在源代码和 PDF 之间双向跳转。本页介绍了设置、构建工作方式（配方和工具）以及 SyncTeX 集成。

LaTeX Workshop 是什么

VS Code 本身不排版 TeX。实际的编译是由您安装在计算机上的发行版完成的 - TeX Live （或 MiKTeX / MacTeX）。 James Yu 的 LaTeX Workshop 是编辑器和该发行版之间的桥梁：它启动构建、预览 PDF，并添加补全、语法突出显示、跳转到 \ref/\cite 的定义、大纲视图等。其市场 ID 是 James-Yu.latex-workshop，超过 500 万次安装 — 实际上是 VS Code 生态系统中的默认 LaTeX 扩展。

一个先决条件是 TeX 命令可以在您的 PATH 上访问。该扩展只是生成 latexmk 或 pdflatex 等可执行文件作为子进程，因此如果 latexmk --version 在终端中工作，则该扩展几乎肯定也会工作。相反，选择引擎或配置日语字体是发行版的问题，而不是扩展的问题。

先在终端编译一次

在调整 VS Code 设置之前，请在终端中构建相同的项目。如果 latexmk 无法在那里运行，则 LaTeX Workshop 也无法启动它。对于第一个文档，请尝试项目文件夹中的其中一个：

latexmk -pdf main.tex
# 日本語 upLaTeX を .latexmkrc に書いた場合 / if .latexmkrc selects upLaTeX
latexmk main.tex

一旦解决了 PATH 和丢失包错误，任何 VS Code 端的故障都会缩小到配方、根文件检测或 PDF 查看器。如果终端构建有效但扩展失败，请检查 settings.json：输出目录、配方名称和占位符是常见的嫌疑对象。

设置

步骤很简单。安装 VS Code，安装 TeX Live（2026 年，TeX Live 2026）等发行版，并确保它位于您的 PATH 上。然后打开扩展视图 (Ctrl/Cmd+Shift+X)，搜索“LaTeX Workshop”并安装它。更改 PATH 后，立即重新启动 VS Code（最好是整个 OS），以便获取新环境。打开 .tex 文件，左侧的 TeX 活动栏图标为您提供构建和预览命令。

Settings 位于 settings.json 中（从 Ctrl/Cmd+, Settings UI，使用右上角的“打开 Settings (JSON)”；您可以编辑全局用户文件或每个项目的 .vscode/settings.json）。首先值得了解的三个关键是：

• latex-workshop.latex.outDir — 中间文件和 PDF 所在的位置。默认为 %DIR%（在 .tex 旁边）。将其设置为例如out 使您的源文件夹保持整洁。
• latex-workshop.latex.autoBuild.run — 触发自动构建的内容：onFileChange（默认；监视依赖项）、onSave（保存时）或 never（仅限手动）。如果您想要可预测的行为，onSave 是一个安全的选择。
• latex-workshop.view.pdf.viewer — PDF 出现的位置：tab（默认；VS Code 内的选项卡）、browser 或 external。对于无摩擦的 SyncTeX，tab 是最佳选择。

最小的起点就是这样 - 在 out/ 中收集输出，在保存时构建，并在内置选项卡中显示 PDF：

{
  "latex-workshop.latex.outDir": "%DIR%/out",
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.view.pdf.viewer": "tab"
}

%DIR% 是一个占位符，它扩展到正在处理的根文件的目录；它再次出现在下面的食谱中。构建后，扩展还可以通过 latex-workshop.latex.autoClean.run 整理或保留中间文件（.aux、.log，...），但解决输出目录和触发器足以了解它。

构建食谱和工具

LaTeX Workshop 中的构建有两层：“工具”和“配方”。 工具 (latex-workshop.latex.tools) 定义要运行的单个命令 - name、command（可执行文件）和 args。 配方 (latex-workshop.latex.recipes) 是工具的有序序列，其中包含列出工具名称的 name 和 tools 数组。像“pdflatex → bibtex → pdflatex → pdflatex”这样的流程（运行参考书目传递然后重新运行）被表示为一个配方。

在没有配置的情况下，扩展使用其内置的默认配方。第一个是单独的 latexmk，这是预期的默认值（当 latex-workshop.latex.recipe.default 是 "first" 时，选择列表中的顶部配方；将其设置为 "lastUsed" 以记住您上次选择的配方）。由于 latexmk 会检查依赖关系并根据需要重新运行多次，因此您无需计算交叉引用、目录或参考书目的传递次数。默认的 latexmk 工具的定义大致如下：

{
  "name": "latexmk",
  "command": "latexmk",
  "args": [
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-outdir=%OUTDIR%",
    "%DOC%"
  ],
  "env": {}
}

读取参数：-synctex=1 发出下面讨论的 SyncTeX 数据； -interaction=nonstopmode 直接运行，而不是在出现错误时停止输入； -file-line-error 将错误打印为“文件：行：消息”，从而可以轻松跳转到有问题的位置。 -pdf 告诉 latexmk 直接通过 pdfLaTeX 生成 PDF。 %OUTDIR% 扩展为您的 outDir，%DOC% 扩展为根文件的路径，不带扩展名（其他占位符包括 %DOCFILE% = 不带扩展名的文件名和 %DIR% = 根目录）。

默认配方还包括引擎变体 latexmk (lualatex) 和 latexmk (xelatex)，以及 latexmk (latexmkrc)，它在没有额外参数的情况下运行 latexmk %DOC%，并将所有内容推迟到 .latexmkrc。对于日本人来说，“把一切都放在 .latexmkrc 中”的方法是最干净的。将 .latexmkrc 放在项目根目录中，并命名引擎和转换器。这是一个 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”路径（$pdf_mode = 1 直接是 pdfLaTeX，4 是LuaLaTeX）。索引通过 upmendex，参考书目通过 upbibtex，它可以很好地处理日语。 %S、%O 和 %D 是 latexmk 的源文件、选项和输出文件的占位符。现在，在 VS Code 方面，您只需选择 latexmk (latexmkrc) 配方，而无需在 settings.json 中编码引擎选择。

如果您希望将所有内容保留在 settings.json 中而不使用 .latexmkrc，请定义您自己的工具和配方，并将日本配方放在第一位。这是一个使用 LuaLaTeX 排版日语的独立示例（通过 luatexja/ltjsclasses 设置日语，既不需要 .latexmkrc 也不需要 dvipdfmx）：

{
  "latex-workshop.latex.tools": [
    {
      "name": "lualatexmk",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-lualatex",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ],
      "env": {}
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "lualatexmk",
      "tools": ["lualatexmk"]
    }
  ],
  "latex-workshop.latex.outDir": "%DIR%/out",
  "latex-workshop.latex.autoBuild.run": "onSave"
}

您还可以将 % !TEX program = ... 或 % !TEX root = ... 等 神奇注释 放在文件顶部，并且 LaTeX Workshop 会尊重它们（通过 latex-workshop.latex.build.enableMagicComments 禁用）。菜谱系统是今天推荐的路径；当您想要在编辑包含的子文件的同时编译主文档时，% !TEX root 在多文件项目中占有一席之地。

固定根文件

在多文件项目中，如果 LaTeX Workshop 猜测错误，它可能会尝试直接编译您正在编辑的子文件。该扩展通过查找 \documentclass、\begin{document} 和 \input/\include 关系来推断根，但对于具有许多章节文件的论文大小项目，显式方向更稳定。

% !TEX root = ../main.tex

\section{実験方法}
この章だけを編集中でも、ビルドは main.tex から始めます。

• 将 % !TEX root = ... 放在子文件的顶部，以便条目文件是明确的。
• 在包含 main.tex 的项目根目录中打开工作区，而不是在独立的章节文件夹中。
• 手动选择菜谱可以覆盖魔法注释，因此在整个团队中保持日常菜谱名称一致。
• 如果一直提示选择 root，请将策略固定在项目的 .vscode/settings.json 中。

SyncTeX 集成

SyncTeX 记录源行和 PDF 中位置之间的对应关系（上面的 -synctex=1 将该映射写入 .synctex.gz）。它可以让您的书写位置和 PDF 视图保持同步。使用内置的 PDF 查看器（viewer 设置为 tab）是最平滑的、无需配置的路径。

正向搜索（来源 → PDF） 从您的编辑位置跳转到 PDF 中的匹配点。快捷方式为 Ctrl+Alt+J（在 Mac 上为 Cmd+Option+J）；在命令面板中，它是“LaTeX Workshop：SyncTeX from cursor”。要在构建后立即自动运行前向搜索，请将 latex-workshop.synctex.afterBuild.enabled 设置为 true。

逆向搜索（PDF → 源） 采用相反的方式，从 PDF 中的某个位置回到匹配的源行。在内置选项卡查看器中，在 PDF 中单击 Ctrl（在 Mac 上单击 Cmd）可将光标移动到该行。单击样式由 latex-workshop.view.pdf.internal.synctex.keybinding 设置，可以是 ctrl-click（默认）或 double-click。一起学习正向/反向对，即使在很长的文档中，您也可以立即跳到正确的位置。

对于日语中的 SyncTeX，有两件事就足够了：将 -synctex=1 传递给 .latexmkrc 中的 $latex（在上面的示例中已完成），并且知道即使通过 DVI ($pdf_mode = 3)，upLaTeX + dvipdfmx 也会携带 SyncTeX 数据。带有外部查看器 (latex-workshop.view.pdf.external.synctex.*) 的 SyncTeX 需要更多配置，因此建议从内置选项卡开始。