VS Code 作为 LaTeX 前端编辑器的配置

Visual Studio Code（简称VS Code）是一个由微软开发，同时支持 Windows 、 Linux 和 macOS 等操作系统的免费编辑器，它支持测试，并内置了 Git 版本控制功能，同时也具有开发环境功能，例如代码补全、代码片段和代码重构等。该编辑器支持用户个性化配置，同时还在编辑器中内置了扩展程序管理的功能。Visual Studio Code 利用插件 LaTeX Workshop 可以配置成一个非常优秀的 LaTeX 前端，网上关于 LaTeX Workshop 配置的文章非常多，但这些配置方案多数都部署了多个 latex tools 和 多个 latex recipes，而多数 recipes 使用的机会都非常少，本文提供一个相对简洁的配置方案，省略那些很少使用的 tools 和 recipes，并且提供偶尔需要用到时的调用方法。

大多数配置的问题

网上给出的大多数配置方案的一个最大的问题是提供的 tools 和 recipes 实在太多，tools 一般都会部署 xelatex、pdflatex 编译命令以及 bibtex 这个参考文献编译命令，有的需求更多一些的还会部署 lualatex，参考文献可能更喜欢用 biblatex 宏包于是又部署了 biber 编译命令，还有用户可能会部署 makeindex 来编译索引、词汇表，高端一些可能还要使用中文索引（指用笔画数或部首来排序的索引），于是还要安装部署 zhmakeindex。这三类命令简单组合就有 12 种 recipes，这还不包括编译命令本身参数的选择，比如如果使用 minted 包来排版语法高亮的代码时必须要使用 -shell-escape 参数来中途跳出到 shell 来运行 pygments 模块。这些正交变量一算上，recipes 的组合数就不得了。

我的配置方案

配置方案的 settings.json 如下（当然，只列出了 latex-workshop 相关的一部分配置）：

{
    "latex-workshop.latex.tools": [
        {
            "name": "latexmk_pdf",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "%DOCFILE%"
            ]
        },
        {
            "name": "latexmk_rconly",
            "command": "latexmk",
            "args": [
                "%DOCFILE%"
            ]
        }
    ],
    "latex-workshop.latex.recipe.default": "first",
    "latex-workshop.latex.recipes": [
        {
            "name": "latexmk",
            "tools": [
                "latexmk_rconly"
            ]
        },
        {
            "name": "latexmk (pdf)",
            "tools": [
                "latexmk_pdf"
            ]
        }
    ],
    "latex-workshop.view.pdf.viewer": "external",
    "latex-workshop.view.pdf.ref.viewer": "external",
    "latex-workshop.view.pdf.external.viewer.command": "C:/Program Files/SumatraPDF/SumatraPDF.exe",
    "latex-workshop.view.pdf.external.viewer.args": [
        "-inverse-search",
        "\"C:/Program Files/Microsoft VS Code/Code.exe\" \"C:/Program Files/Microsoft VS Code/resources/app/out/cli.js\" -r -g \"%f:%l\"",
        // "code.cmd -r -g \"%f:%l\"",
        "%PDF%"
    ],
    "latex-workshop.view.pdf.external.synctex.command": "C:/Program Files/SumatraPDF/SumatraPDF.exe",
    "latex-workshop.view.pdf.external.synctex.args": [
        "-forward-search",
        "%TEX%",
        "%LINE%",
        "%PDF%",
    ],
}

这个配置方案只部署了两个 tools，均使用了自动编译工具 latexmk。其中，latexmk_pdf 指定了编译的参数，而 latexmk_rconly 不指定任何参数，由 latexmk 的配置文件决定。对应的两个 recipes 分别使用了这两个工具。latexmk 可以由 C:\latexmk\LatexMK 文件（Windows 系统下，其他系统下的路径请自行查找 latemk 手册）全局控制，或由项目文件夹下的 latexmkrc 或 .latexmkrc 文件控制。我的 LatexMK 文件内容如下：

$pdf_mode = 5;
$xelatex = "xelatex -file-line-error -halt-on-error -interaction=nonstopmode -no-pdf -synctex=1 %O %S";
$xdvipdfmx = "xdvipdfmx -E -o %D %O %S";
$bibtex_use = 1.5;
$clean_ext = "hd nav snm xdv listing vrb run.xml";

该文件实际是一个 perl 脚本，为 latexmk 的执行传递了参数。其中；

• $pdf_mode 指定编译命令和输出文件格式。
  • 该值为 0：不生成 .pdf 文件；
  • 该值为 1：通过 $pdflatex 变量配置的 pdflatex 命令编译成 .pdf 文件；
  • 该值为 2：通过 $latex 变量配置的 latex 命令编译成 .dvi 文件，并通过由 $dvips 变量配置的驱动 dvips 转换成 .ps 文件，再由 $ps2pdf 变量配置的工具 ps2pdf 转换成 .pdf 文件；
  • 该值为 3：通过 $latex 变量配置的 latex 命令编译成 .dvi 文件，并通过由 $dvipdf 变量配置的驱动 dvipdfm(x) 转换成 .pdf 文件；
  • 该值为 4：通过 $lualatex 变量配置的 lualatex 命令编译成 .pdf 文件；
  • 该值为 5：通过 $xelatex 变量配置的 xelatex 命令编译，使用由 $xdvipdfmx 变量配置的驱动 xdvipdfmx 转换成 .pdf 文件。
• $xelatex 指定了使用 xelatex 命令编译时的命令及参数。
• $xdvipdfmx 指定使用 xdvipdfmx 驱动时的命令及参数。
• $bibtex_use 指定参考文献的编译方式
  • 该值为 0: 不使用 bibtex 或 biber，清理文件时也不删除 .bbl 临时文件；
  • 该值为 1：仅当 .bib 存在时 使用 bibtex 或 biber，清理文件时也不删除 .bbl 临时文件；
  • 该值为 1.5： 仅当 .bib 存在时 使用 bibtex 或 biber，清理文件时有条件地删除 .bbl 临时文件（.bib 文件存在时）；
  • 该值为 2：发现有更新 .bbl 的需要时即使用 bibtex 或 biber，不监测 .bib 文件的存在，清理文件时总是清除 .bbl 文件。
• $clean_ext 指定使用 -c 选项清理中间临时文件时，需要额外清理的文件扩展名。

此外，如有需要还可以设置其他参数，详见 latexmk 手册。由于本人日常撰写的文档都是中文文档，所以将 xelatex 编译链作为了默认编译链。进行这样的设置后，在 VS Code 编辑器内使用快捷键 Ctrl+Alt+B 即可调用 latexmk 这一 recipes 进行编译，如果需要使用 pdflatex 编译西文文档时，Ctrl+Alt+X 调出 TeX 面板，选择 latexmk(pdf) 这一 recipes 即可，编译方案少了，对应的菜单项很容易找。

如果编译项目需要使用一些特殊参数，可以通过项目文件夹下的 latexmkrc 或 .latexmkrc 设置。其与 C:\latexmk\LatexMK 的内容是相似的，在 latexmk 运行时会在 C:\latexmk\LatexMK 之后被读入，因此，文件中的设置将覆盖全局设置。如果一个项目的编译需要开启 -shell-escape 参数，就可以在项目的 latexmkrc 中写成：

$xelatex = "xelatex -file-line-error -halt-on-error -shell-escape -interaction=nonstopmode -no-pdf -synctex=1 %O %S";

然后照常使用 Ctrl+Alt+B 进行编译即可。

如果作为开发测试，只需要一遍编译，或者只需要使用某个驱动、工具时，不妨 Ctrl+ ` 调出终端，直接在终端文件夹下使用命令行编译。作为开发调试，这个问题应该不在话下。

至于 VS Code 和 SumatraPDF 之间的正反向搜索，其实与 Notedad++配置 差别不大，具体不再赘述。只需要注意一点，不要因为系统变量 path 中给定了 VS Code 的路径就偷懒不写路径地址。因为 path 中给定的路径 C:\Program Files\Microsoft VS Code\bin 并不是 code.exe 所在的路径，命令中的 code 实际指向的是这个路径下的一个 Windows 脚本—— code.cmd，其内容为：

@echo off
setlocal
set VSCODE_DEV=
set ELECTRON_RUN_AS_NODE = 1
"%~dp0..\Code.exe" "%~dp0..\resource\app\out\cli.js" %*
endlocal

所以，latex-workshop.view.pdf.external.viewer.args 的反向搜索参数可以设置成为：

"code.cmd -r -g \"%f:%l\""

即，使用配置文件中被注释的一行替代上一行。不过这样设置在 SumtraPDF 中双击返回代码时会先跳出一个 cmd 黑窗口，视觉上非常不爽。

我因为常写 A3 横排的文本所以不使用 VS Code 的内置 PDF 浏览器，毕竟那样的话文本浏览窗口太小了，还是用 SumatraPDF 放到另一个显示器上看得舒服。如果你屏幕足够大，而且只写 A4 大小的文本，VS Code 内置的 PDF 浏览器就很好用，正反向搜索选择也是默认配置好的，不需要额外设置，只是反向搜索需要 Ctrl + 双击。