VSCode / Cursor 中 LaTeX Workshop 的 settings.json 配置：编译与 SyncTeX 跳转

在 VSCode 或 Cursor 中写 LaTeX，LaTeX Workshop是必备扩展，支持编译、PDF 预览、错误定位，以及 PDF 和源码之间的双向跳转。本文仅介绍其settings.json配置，适用于已安装 LaTeX Workshop 扩展与 TeX Live / MiKTeX 的场景。

完整配置

LaTeX Workshop 的配置可以放入项目级配置文件：

.vscode/settings.json

也可以放入用户级settings.json中。一般建议：和项目编译方式强相关的配置放在项目级.vscode/settings.json中，个人通用习惯放在用户级settings.json中。

个人使用配置如下：

{// >>>>>>>>>> latex 配置 >>>>>>>>>>"latex-workshop.showContextMenu":true,"latex-workshop.latex.autoBuild.run":"onSave","latex-workshop.latex.recipe.default":"lastUsed","latex-workshop.view.pdf.viewer":"tab","latex-workshop.view.pdf.tab.editorGroup":"right","latex-workshop.view.pdf.internal.synctex.keybinding":"double-click","latex-workshop.synctex.indicator":"rectangle","latex-workshop.latex.recipes":[{"name":"latexmk (pdf)","tools":["latexmk-pdf"]},{"name":"pdflatex -> bibtex -> pdflatex * 2","tools":["pdflatex","bibtex","pdflatex","pdflatex"]},{"name":"latexmk (xelatex)","tools":["xelatexmk"]},{"name":"xelatex -> bibtex -> xelatex * 2","tools":["xelatex","bibtex","xelatex","xelatex"]}],"latex-workshop.latex.tools":[{"name":"latexmk-pdf","command":"latexmk","args":["-pdf","-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"pdflatex","command":"pdflatex","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"bibtex","command":"bibtex","args":["%DOCFILE%"]},{"name":"xelatexmk","command":"latexmk","args":["-xelatex","-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"xelatex","command":"xelatex","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]}]// <<<<<<<<<< latex 配置 <<<<<<<<<<}

配置解析

1. 右键菜单与自动编译

"latex-workshop.showContextMenu":true,"latex-workshop.latex.autoBuild.run":"onSave","latex-workshop.latex.recipe.default":"lastUsed"

latex-workshop.showContextMenu用于开启右键菜单。开启后，在.tex文件中右键可以看到：

Build LaTeX project SyncTeX from cursor

latex-workshop.latex.autoBuild.run设置自动编译时机。这里使用：

"onSave"

表示保存.tex文件时自动编译。常见取值还有：

"never"

表示不自动编译，只手动编译。

"onFileChange"

表示文件变化时自动编译，触发更频繁。

latex-workshop.latex.recipe.default设置默认编译方案。这里默认使用：

"latexmk (pdf)"

这个名字必须和latex-workshop.latex.recipes中某个 recipe 的name完全一致。

2. PDF 预览设置

"latex-workshop.view.pdf.viewer":"tab","latex-workshop.view.pdf.tab.editorGroup":"right"

latex-workshop.view.pdf.viewer设置 PDF 打开方式。这里使用：

"tab"

表示在 VSCode / Cursor 的编辑器 tab 中打开 PDF。

latex-workshop.view.pdf.tab.editorGroup设置 PDF 打开位置。这里使用：

"right"

表示 PDF 默认在右侧编辑器组打开，方便形成左侧源码、右侧 PDF 的布局。

常见取值包括：

"current""left""right""above""below"

3. SyncTeX 跳转设置

"latex-workshop.view.pdf.internal.synctex.keybinding":"double-click","latex-workshop.synctex.indicator":"rectangle"

latex-workshop.view.pdf.internal.synctex.keybinding控制 PDF 到源码的反向跳转方式。这里设置为：

"double-click"

表示在 PDF 中双击某个位置，可以跳回对应的.tex源码位置。另一个常见值是：

"ctrl-click"

表示使用Ctrl + Click跳转。

latex-workshop.synctex.indicator控制源码跳到 PDF 时的提示样式。可选值包括：

"none""circle""rectangle"

这里使用：

"rectangle"

表示在 PDF 中用矩形标出跳转位置。

源码跳 PDF 可以在.tex文件中右键选择：

SyncTeX from cursor

也可以在命令面板中执行：

LaTeX Workshop: SyncTeX from cursor

4. 常用编译参数

下面几个参数通常建议保留：

"-synctex=1","-interaction=nonstopmode","-file-line-error"

-synctex=1用于生成 SyncTeX 文件，支持 PDF 和源码双向跳转。开启后通常会生成：

main.synctex.gz

-interaction=nonstopmode表示编译遇到错误时不要停下来等待用户输入。没有这个参数时，LaTeX 出错可能会卡在终端中。

-file-line-error表示错误信息中包含文件名和行号，方便 VSCode / Cursor 定位错误。

%DOC%是 LaTeX Workshop 的占位符，表示当前主.tex文件。

%DOCFILE%表示主文件名，不带扩展名，常用于bibtex。

编译方式配置

1. recipes：定义编译方案

"latex-workshop.latex.recipes":[{"name":"latexmk (pdf)","tools":["latexmk-pdf"]},{"name":"pdflatex -> bibtex -> pdflatex * 2","tools":["pdflatex","bibtex","pdflatex","pdflatex"]},{"name":"latexmk (xelatex)","tools":["xelatexmk"]},{"name":"xelatex -> bibtex -> xelatex * 2","tools":["xelatex","bibtex","xelatex","xelatex"]}]

recipes用来定义“编译方案”。每个 recipe 可以调用一个或多个 tool。

这里配置了四种常见方案：

• latexmk (pdf)：推荐默认方案，自动处理多次编译、参考文献和交叉引用。
• pdflatex -> bibtex -> pdflatex * 2：传统 BibTeX 编译流程。
• latexmk (xelatex)：使用latexmk调用xelatex。
• xelatex -> bibtex -> xelatex * 2：传统xelatex + bibtex编译流程。

传统 BibTeX 流程等价于手动执行：

pdflatex main.tex bibtex main pdflatex main.tex pdflatex main.tex

2. tools：定义具体命令

"latex-workshop.latex.tools":[{"name":"latexmk-pdf","command":"latexmk","args":["-pdf","-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"pdflatex","command":"pdflatex","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"bibtex","command":"bibtex","args":["%DOCFILE%"]},{"name":"xelatexmk","command":"latexmk","args":["-xelatex","-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]},{"name":"xelatex","command":"xelatex","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","%DOC%"]}]

tools定义具体执行的命令。recipe 中引用的是 tool 的name。

例如：

{"name":"latexmk (pdf)","tools":["latexmk-pdf"]}

会调用：

{"name":"latexmk-pdf","command":"latexmk"}

实际执行的命令大致是：

latexmk-pdf-synctex=1-interaction=nonstopmode -file-line-error main.tex

3. latexmk 与手动流程的区别

使用：

"tools":["latexmk-pdf"]

表示交给latexmk自动判断编译流程。它会自动处理：

• 是否需要多次运行pdflatex
• 是否需要运行bibtex
• 参考文献是否更新
• 交叉引用是否稳定

使用：

"tools":["pdflatex","bibtex","pdflatex","pdflatex"]

表示固定执行四步。

固定流程更直观，但不如latexmk智能。日常写论文时，更推荐使用latexmk。

4. pdflatex 与 xelatex 怎么选

pdflatex是英文论文中最常见的编译方式，适合大多数期刊模板。

xelatex常用于：

• 中文文档
• 需要系统字体
• Unicode 字符较多
• 使用fontspec、xeCJK等宏包

如果没有特殊字体或中文需求，默认使用latexmk (pdf)通常最稳妥。

推荐日常用法

日常写 LaTeX 时，推荐使用默认方案：

"latex-workshop.latex.recipe.default":"latexmk (pdf)"

保存文件后自动编译：

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

PDF 预览放在右侧：

"latex-workshop.view.pdf.tab.editorGroup":"right"

PDF 跳源码使用双击：

"latex-workshop.view.pdf.internal.synctex.keybinding":"double-click"

总结

这份settings.json的核心思路是：

• 用latexmk (pdf)作为默认编译方式
• 用-synctex=1支持 PDF 和源码双向跳转
• 用-interaction=nonstopmode避免编译出错时卡住
• 用-file-line-error提供清晰的错误定位
• 用右侧 tab 预览 PDF
• 用双击实现 PDF 到源码的反向跳转

对于大多数英文论文和期刊模板，latexmk (pdf)是最省心、最稳定的默认选择。