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

迷路爸爸1802026-05-05 8:16

文章目录

    • 完整配置
    • 配置解析
      • [1. 右键菜单与自动编译](#1. 右键菜单与自动编译)
      • [2. PDF 预览设置](#2. PDF 预览设置)
      • [3. SyncTeX 跳转设置](#3. SyncTeX 跳转设置)
      • [4. 常用编译参数](#4. 常用编译参数)
    • 编译方式配置
      • [1. recipes：定义编译方案](#1. recipes：定义编译方案)
      • [2. tools：定义具体命令](#2. tools：定义具体命令)
      • [3. latexmk 与手动流程的区别](#3. latexmk 与手动流程的区别)
      • [4. pdflatex 与 xelatex 怎么选](#4. pdflatex 与 xelatex 怎么选)
    • 推荐日常用法
    • 总结

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

完整配置

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

text 复制代码 
.vscode/settings.json

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

个人使用配置如下：

json 复制代码 
{
  "latex-workshop.showContextMenu": true,
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.latex.recipe.default": "latexmk (pdf)",

  "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%"
      ]
    }
  ]
}

配置解析

1. 右键菜单与自动编译

json 复制代码 
"latex-workshop.showContextMenu": true,
"latex-workshop.latex.autoBuild.run": "onSave",
"latex-workshop.latex.recipe.default": "latexmk (pdf)"

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

text 复制代码 
Build LaTeX project
SyncTeX from cursor

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

json 复制代码 
"onSave"

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

json 复制代码 
"never"

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

json 复制代码 
"onFileChange"

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

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

json 复制代码 
"latexmk (pdf)"

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

2. PDF 预览设置

json 复制代码 
"latex-workshop.view.pdf.viewer": "tab",
"latex-workshop.view.pdf.tab.editorGroup": "right"

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

json 复制代码 
"tab"

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

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

json 复制代码 
"right"

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

常见取值包括：

json 复制代码 
"current"
"left"
"right"
"above"
"below"

3. SyncTeX 跳转设置

json 复制代码 
"latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
"latex-workshop.synctex.indicator": "rectangle"

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

json 复制代码 
"double-click"

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

json 复制代码 
"ctrl-click"

表示使用 Ctrl + Click 跳转。

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

json 复制代码 
"none"
"circle"
"rectangle"

这里使用：

json 复制代码 
"rectangle"

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

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

text 复制代码 
SyncTeX from cursor

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

text 复制代码 
LaTeX Workshop: SyncTeX from cursor

4. 常用编译参数

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

json 复制代码 
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error"

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

text 复制代码 
main.synctex.gz

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

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

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

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

编译方式配置

1. recipes：定义编译方案

json 复制代码 
"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 流程等价于手动执行：

bash 复制代码 
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex

2. tools：定义具体命令

json 复制代码 
"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。

例如：

json 复制代码 
{
  "name": "latexmk (pdf)",
  "tools": [
    "latexmk-pdf"
  ]
}

会调用：

json 复制代码 
{
  "name": "latexmk-pdf",
  "command": "latexmk"
}

实际执行的命令大致是：

bash 复制代码 
latexmk -pdf -synctex=1 -interaction=nonstopmode -file-line-error main.tex

3. latexmk 与手动流程的区别

使用：

json 复制代码 
"tools": [
  "latexmk-pdf"
]

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

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

使用：

json 复制代码 
"tools": [
  "pdflatex",
  "bibtex",
  "pdflatex",
  "pdflatex"
]

表示固定执行四步。

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

4. pdflatex 与 xelatex 怎么选

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

xelatex 常用于：

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

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

推荐日常用法

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

json 复制代码 
"latex-workshop.latex.recipe.default": "latexmk (pdf)"

保存文件后自动编译：

json 复制代码 
"latex-workshop.latex.autoBuild.run": "onSave"

PDF 预览放在右侧：

json 复制代码 
"latex-workshop.view.pdf.tab.editorGroup": "right"

PDF 跳源码使用双击：

json 复制代码 
"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) 是最省心、最稳定的默认选择。

相关推荐
Lhan.zzZ9 小时前
笔记_2026.4.28_004
c++·ide·笔记·qt
π同学16 小时前
ESP-IDF+vscode开发ESP32第十一讲——LEDC
vscode·pwm·eps32
吴声子夜歌17 小时前
Node.js——JSON-Server轻量级RESTful API
node.js·json·restful·json-server
呆萌的代Ma20 小时前
解决n8n的输入内容报错JSON parameter needs to be valid JSON
json·n8n
一帘忧梦1 天前
vscode 搭建stm32开发环境 +HAL 库
ide·vscode·编辑器
weixin_416660071 天前
豆包公式转Word，乱码解决
word·latex·豆包
独隅2 天前
Visual Studio 2026 详细安装教程和配置指南
ide·visual studio
Robot_Nav2 天前
AI 编程助手 Skill 完全指南：VS Code · Trae CN · Claude Code
人工智能·vscode·skill·trae·claude code
lifewange2 天前
Pycharm和IDEA中安装Cursor的方法
ide·pycharm·intellij-idea
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03【AI】2026 年具身智能模型和世界模型总结04Codex 接入 DeepSeek API 完整配置文档05零基础教你claude code 接入 deepseek V406裂开！ChatGPT 居然开始要手机号验证，附详细解决方法072026年AI前瞻：量子AI、具身智能与科学发现的新纪元08几个好用的ip纯净度检测网站09CC-Switch & Claude 基于 Linux 服务器安装使用指南10CVE-2026-31431 (Copy Fail) 漏洞复现与验证记录