LaTeX VSCode 配置

配置概述

LaTeX WorkShop 插件的编译逻辑分为两层：第一层为recipe，第二层为tool，具有如下特点：

一个recipe由若干个tool组成
在配置文件中可以提供多个recipe和多个tool；
直接点击编译按钮会自动选择第一个（或上一次使用的）recipe来执行编译；
一个tool通常包括一个单独的编译命令加上若干参数，例如xelatex，lualatex和pdflatex等，还可能是处理参考文献需要的bibtex或biber；
一个recipe会依次执行它所包含的tool，例如：
1
xelatex -> bibtex -> xelatex -> xelatex

列举并解释一下在 VSCode 的 LaTeX WorkShop 插件的常见配置中出现的选项：

-synctex=1：启用 SyncTeX 支持，用于在源文件和生成的 PDF 间建立同步的技术，允许通过 PDF 文件快速定位到源文件的特定位置
-interaction=nonstopmode：设置交互模式为非停止模式，这个选项告诉 \(\TeX\) 编译器在遇到错误时不停止编译，而是继续处理下去，可以让编译过程在错误发生时不中断，而是生成尽可能多的输出信息
-file-line-error：启用文件行错误信息，当编译出错时，会显示错误的行号以及文件名，帮助定位问题所在
-shell-escape：允许 LaTeX 引擎执行外部的 shell 命令。这个选项潜在地增加了潜在的安全风险，在使用 minted 宏包进行代码高亮（它需要运行外部的 Python 来高亮代码），或使用 pgfplots 或 tikz 等绘图宏包时，它们可能会调用外部程序。

还有 latexmk 支持的选项：

指定具体的\(\TeX\)编译命令
1. -xelatex：指定xelatex并生成 pdf
2. -lualatex：指定lualatex并生成 pdf
-outdir=：指定输出位置
-auxidr=：指定辅助文件的存放位置（下面采用了./.aux作为杂项文件的存放位置）
-pdf：指定输出 pdf

这些选项并不是插件所需要的，而是会被直接传递给xelatex等编译命令，或者latexmk。对于 LaTeX WorkShop 插件，还需要在命令中传递特殊变量%DOC%或%DOCFILE%代表当前文件，第一个只是文件名不含后缀，第二个则是文件名加上完整路径，略有区别。

编译配置（一）

第一种配置是使用latexmk分别调用xelatex，lualatex和pdflatex，配置如下

// latex基本工具链 latex-workshop.latex.tools
"latex-workshop.latex.tools": [
    {
        "name": "xelatexmk",
        "command": "latexmk",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-xelatex",
            "-auxdir=%DIR%/.aux",
            "-outdir=%OUTDIR%",
            "%DOC%"
        ],
        "env": {}
    },
    {
        "name": "lualatexmk",
        "command": "latexmk",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-lualatex",
            "-outdir=%OUTDIR%",
            "-auxdir=%DIR%/.aux",
            "%DOC%"
        ],
        "env": {}
    },
    {
        "name": "latexmk",
        "command": "latexmk",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-pdf",
            "-outdir=%OUTDIR%",
            "-auxdir=%DIR%/.aux",
            "%DOC%"
        ]
    }
],
// latex组合工具链 latex-workshop.latex.recipes
"latex-workshop.latex.recipes": [
    {
        "name": "XeLaTeXmk",
        "tools": [
            "xelatexmk"
        ]
    },
    {
        "name": "LuaLaTeXmk",
        "tools": [
            "lualatexmk"
        ]
    },
    {
        "name": "LaTeXmk",
        "tools": [
            "latexmk"
        ]
    }
],

编译配置（二）

第二种配置是不使用 latexmk，直接使用xelatex等编译命令，此时由于参考文献（bibtex或biber）和双向引用等原因，需要配置recipe进行多次编译，配置如下

"latex-workshop.latex.tools": [
    {
        "name": "xelatex",
        "command": "xelatex",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOCFILE%"
        ]
    },
    {
        "name": "pdflatex",
        "command": "pdflatex",
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOCFILE%"
        ]
    },
    {
        "name": "bibtex",
        "command": "bibtex",
        "args": [
            "%DOCFILE%"
        ]
    }
],
"latex-workshop.latex.recipes": [
    {
        "name": "xelatex->xelatex",
        "tools": [
            "xelatex",
            "xelatex"
        ]
    },
    {
        "name": "xelatex",
        "tools": [
            "xelatex"
        ]
    },
    {
        "name": "pdflatex",
        "tools": [
            "pdflatex"
        ]
    },
    {
        "name": "BibTeX",
        "tools": [
            "bibtex"
        ]
    },
    {
        "name": "xe->bib->xe*2",
        "tools": [
            "xelatex",
            "bibtex",
            "xelatex",
            "xelatex"
        ]
    },
    {
        "name": "pdf->bib->pdf*2",
        "tools": [
            "pdflatex",
            "bibtex",
            "pdflatex",
            "pdflatex"
        ]
    }
],

VSCode与SumatraPDF双向跳转

除了 tools 和 recipes 这两个主要的配置，还有一个重要的功能是使用SumatraPDF进行PDF预览，并且支持VSCode和SumatraPDF之间的双向跳转。通过VSCode内部预览PDF时，可以直接进行双向跳转，无需配置。默认的双向跳转操作是：

ctrl + 单击PDF相应位置，从PDF跳转到源文件对应位置
ctrl+alt+j，从源文件跳转到PDF对应位置

对于VSCode的配置如下：

"latex-workshop.view.pdf.viewer": "external",
"latex-workshop.view.pdf.external.synctex.command": "<path-to-SumatraPDF>/SumatraPDF.exe",
"latex-workshop.view.pdf.external.synctex.args": [
    "-forward-search",
    "%TEX%",
    "%LINE%",
    "-reuse-instance",
    "-inverse-search",
    "\"<path-to-vscode>/Code.exe\" --ms-enable-electron-run-as-node \"<path-to-vscode>/resources/app/out/cli.js\"  -r -g \"%f:%l\"",
    "%PDF%"
],

对于SumatraPDF的配置为：

1	"<path-to-vscode>/Code.exe" --ms-enable-electron-run-as-node "<path-to-vscode>/resources/app/out/cli.js" -r -g %f:%l

如果打开SumatraPDF的设置面板找不到Set inverse command-line这个项，需要在高级选项中首先打开Tex增强选项：EnableTeXEnhancements = true， Set inverse command-line在配置文件中实际上是 InverseSearchCmdLine = ... 这一项。

尤其要注意配置中的参数顺序，--ms-enable-electron-run-as-node需要出现在cli.js之前，否则跳转可能会中断在cli.js文件。

对双向跳转功能进行如下测试：

单独启动SumatraPDF，跳转到源文件（自动使用VSCode打开），然会再跳转回去；
单独启动VSCode，跳转到PDF（自动使用SumatraPDF打开），然后再跳转回去。

当前的配置是可以正常跳转的。

注意：双向跳转的功能可能因为配置的细小差别，VSCode与SumatraPDF的版本更新等而失效，在网上有很多种解决办法，具体的命令细节也不尽相同，效果各异。有些配置可能已经过时了，对新版本不再生效。当前（2024年2月28日）配置使用的VSCode版本为1.86.2，SumatraPDF版本为v3.5.2-64bit。

非常遗憾的是，上面的这个配置仍然只能在受限的条件下正常工作：不依赖于VSCode，独立地使用SumatraPDF打开PDF文件，然后可以正常跳转。由于通过SumatraPDF启动VSCode时只是打开文件而非文件夹，因此最好的方式就是单独地用vscode打开tex文件，用SumatraPDF和PDF文件，然后进行双向跳转。

如果VS Code无法打开SumatraPDF，可以试着把SumatraPDF.exe的路径添加到环境变量PATH。

补充

除了最主要的编译和双向跳转，还有一些可能有用的，与LaTeX相关的辅助性配置

"[latex]": {
    "editor.defaultFormatter": "James-Yu.latex-workshop",
    "editor.unicodeHighlight.allowedLocales": {
        "zh-hans": true
    },
    "editor.rulers": [
        100
    ],
},
"latex-workshop.intellisense.unimathsymbols.enabled": true,
"latex-workshop.showContextMenu": true,