VSCode LaTeX WorkShop 配置

基础概念

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

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

下文中编译命令及其选项可以参考其它几篇关于LaTeX的笔记，LaTeX WorkShop 插件只是对这些编译命令进行了封装。此外，LaTeX WorkShop 插件会在命令中传递特殊变量%DOC%或%DOCFILE%代表当前文件，第一个只是文件名不含后缀，第二个则是文件名加上完整路径，略有区别。

由于插件也只是调用了pdflatex、latexmk等编译命令，如果环境中存在.latexmkrc等配置文件，可能会对插件的编译行为造成影响。但是因为插件的选项是通过命令行参数传递的，优先级更高，影响应该不大。

LaTeX WorkShop 插件并不推荐使用例如% !TEX program = xelatex的魔法命令来指定编译命令，但是考虑到向后兼容性会为其提供有限的支持。

编译配置（一）

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

// latex基本工具链 latex-workshop.latex.tools
"latex-workshop.latex.tools": [
    {
        "name": "xelatexmk",
        "command": "latexmk",
        "args": [
            "-file-line-error",
            "-halt-on-error",
            "-interaction=nonstopmode",
            "-synctex=1",
            "-xelatex",
            "-auxdir=%DIR%/.aux",
            "-outdir=%OUTDIR%",
            "%DOC%"
        ],
        "env": {}
    },
    {
        "name": "lualatexmk",
        "command": "latexmk",
        "args": [
            "-file-line-error",
            "-halt-on-error",
            "-interaction=nonstopmode",
            "-synctex=1",
            "-lualatex",
            "-outdir=%OUTDIR%",
            "-auxdir=%DIR%/.aux",
            "%DOC%"
        ],
        "env": {}
    },
    {
        "name": "latexmk",
        "command": "latexmk",
        "args": [
            "-file-line-error",
            "-halt-on-error",
            "-interaction=nonstopmode",
            "-synctex=1",
            "-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"
        ]
    }
],

在某些情况下的编译可能需要加上 "-shell-escape" 选项。

编译配置（二）

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

"latex-workshop.latex.tools": [
    {
        "name": "xelatex",
        "command": "xelatex",
        "args": [
            "-file-line-error",
            "-halt-on-error",
            "-interaction=nonstopmode",
            "-synctex=1",
            "%DOCFILE%"
        ]
    },
    {
        "name": "pdflatex",
        "command": "pdflatex",
        "args": [
            "-file-line-error",
            "-halt-on-error",
            "-interaction=nonstopmode",
            "-synctex=1",
            "%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"
        ]
    }
],

这组配置并没有使用.aux/子目录存放辅助文件，因为这些编译命令虽然支持指定输出目录，但是无法自动创建目录。

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。

VSCode 补充配置

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

"[latex]": {
    "editor.defaultFormatter": "James-Yu.latex-workshop",
    "editor.wordWrap": "on",
    "editor.unicodeHighlight.allowedLocales": {
        "zh-hans": true,
        "zh-hant": true
    },
    "editor.formatOnSave": false,
},
"latex-workshop.intellisense.unimathsymbols.enabled": true,
"latex-workshop.showContextMenu": true,
"latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
"latex-workshop.latex.autoBuild.cleanAndRetry.enabled": false,
"latex-workshop.latex.recipe.default": "lastUsed",
"latex-workshop.latex.clean.args": [
    "-outdir=%OUTDIR%",
    "-c",
    "%TEX%",
    "-auxdir=%DIR%/.aux"
],
"latex-workshop.message.error.show": false,
"latex-workshop.message.warning.show": false,

这里有几个是值得注意的：

latex-workshop.latex.recipe.default：使用上一次的recipe，插件默认会使用第一个recipe；
latex-workshop.latex.clean.args：如果使用.aux/辅助目录，这里也需要加上参数，否则插件无法进行清理。