VS Code LaTeX 自动编译设置全攻略（含插件配置 + 自动保存）

问题描述

VS Code 可通过配置文件（如 tasks.json）实现代码自动编译，避免手动输入编译命令的重复操作。

在 VS Code 中配置了 LaTeX Workshop 插件，但设置自动编译后（例如将 latex-workshop.latex.autoBuild.run 设为 onFileChange），修改 .tex 文件时并未触发自动编译，手动编译可正常执行，如何排查并解决这一自动编译失效的问题？

---

原因分析

导致 VS Code 中 LaTeX Workshop 插件无法自动编译的可能原因可从以下两方面分析：

1. 配置文件设置问题：若 settings.json 中与自动编译相关的配置存在疏漏（例如 latex-workshop.latex.autoBuild.run 未正确设置为 onFileChange 或 onSave，或未配置对应的编译工具链 latex-workshop.latex.tools 及配方 latex-workshop.latex.recipes），会导致插件无法识别自动编译触发条件或找不到有效的编译方式，从而使自动编译失效。
2. VS Code 未开启自动保存：若 VS Code 的文件自动保存功能未启用（即未勾选 Files: Auto Save 相关选项），即使将 latex-workshop.latex.autoBuild.run 设为 onFileChange 或 onSave，也需手动按 Ctrl+S 保存文件才可能触发编译；若未手动保存，插件因未检测到文件状态变化，自然不会执行自动编译。

---

解决方案

基础设置

基本设置已经有很多人分享了，如果下述不够详细也可以查阅其他说明文档。

打开VS Code 左下角的设置

​​​​​​​​

打开设置json文件，点击右上角图标会出现打开settings.json文件

复制下列代码到json文件中

    //------------------------------LaTeX 配置----------------------------------
    //右键菜单
    "latex-workshop.showContextMenu":true,
    //从使用的包中自动补全命令和环境
    "latex-workshop.intellisense.package.enabled": true,
    //编译出错时设置是否弹出气泡设置
    "latex-workshop.message.error.show": false,
    "latex-workshop.message.warning.show": false,
    // 编译工具和命令
    "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": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOCFILE%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ]
        }
    ],
    // 用于配置编译链
    "latex-workshop.latex.recipes": [
        {
            "name": "XeLaTeX",
            "tools": [
                "xelatex"
            ]
        },
        {
            "name": "PDFLaTeX",
            "tools": [
                "pdflatex"
            ]
        },
        {
            "name": "BibTeX",
            "tools": [
                "bibtex"
            ]
        },
        {
            "name": "LaTeXmk",
            "tools": [
                "latexmk"
            ]
        },
        {
            "name": "xelatex -> bibtex -> xelatex*2",
            "tools": [
                "xelatex",
                "bibtex",
                "xelatex",
                "xelatex"
            ]
        },
        {
            "name": "pdflatex -> bibtex -> pdflatex*2",
            "tools": [
                "pdflatex",
                "bibtex",
                "pdflatex",
                "pdflatex"
            ]
        }
    ],
    //文件清理。此属性必须是字符串数组
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux",
        "*.bbl",
        "*.blg",
        "*.idx",
        "*.ind",
        "*.lof",
        "*.lot",
        "*.out",
        "*.toc",
        "*.acn",
        "*.acr",
        "*.alg",
        "*.glg",
        "*.glo",
        "*.gls",
        "*.ist",
        "*.fls",
        "*.log",
        "*.fdb_latexmk"
    ],
    //设置为onFaild 在构建失败后清除辅助文件
    "latex-workshop.latex.autoClean.run": "onFailed",
    // 使用上次的recipe编译组合
    "latex-workshop.latex.recipe.default": "lastUsed",
    // 自动编译
    "latex-workshop.latex.autoBuild.run": "onFileChange",
    // 自动换行
    "editor.wordWrap": "on",
    // 用于反向同步的内部查看器的键绑定。ctrl/cmd +点击(默认)或双击
    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
    "workbench.editorAssociations": {
        "*.npy": "numpy.preview"
    },

提示：处理规则如下 ——JSON 文件为空时，将目标内容放入大括号 {} 内；文件已有内容时，先在原有内容后加逗号，再把上述内容复制到文件中。

检查配置文件

在 LaTeX Workshop 插件中，“latex-workshop.latex.autoBuild.run” 配置项用于设置自动编译的触发方式，主要有以下几种选择：

1. “never”：禁用自动编译，需手动触发编译操作。
2. “onFileChange”：当检测到文件（如 .tex 源文件）发生修改并保存时，自动触发编译。
3. “onSave”：仅在手动保存文件时触发自动编译（部分场景下与 onFileChange 行为类似，具体取决于文件监听机制）。

不同选项可根据开发习惯调整，onFileChange 适合需要实时预览编译结果的场景，never 则适合希望完全手动控制编译时机的情况。

如果你需要的是全自动编译则使用：

    // 自动编译
    "latex-workshop.latex.autoBuild.run": "onFileChange",

提示：需要删除所有其余"latex-workshop.latex.autoBuild.run"的设置，只保留一行。

检查VS Code 是否开启自动保存

打开VS Code 左下角的设置

​​​​​​​​

在设置搜索中输入auto save

设置Auto Save

在 VS Code 的文件自动保存设置（Files: Auto Save）中，确实包含多种选项，默认情况下通常为 off（即关闭自动保存），这可能导致 LaTeX 自动编译因未检测到文件保存动作而失效。若需配合自动编译功能，一般建议将其修改为 afterDelay（延迟自动保存），具体说明如下：

1. off：默认值，需手动按 Ctrl+S 保存文件，若未手动保存，即使 LaTeX 插件设置了 onFileChange 或 onSave，也无法触发自动编译。
2. afterDelay：文件修改后延迟一定时间（可通过 Files: Auto Save Delay 设置，默认 1000 毫秒）自动保存，能确保修改被及时记录，从而触发 LaTeX 插件的自动编译逻辑，是兼顾操作流畅性与自动触发的常用选择。
3. 其他选项（如 onFocusChange 切换窗口时保存、onWindowChange 切换应用时保存）虽也能触发保存，但 afterDelay 更贴合实时编辑时的自动编译需求。

因此，若要解决自动编译失效问题，除检查 LaTeX Workshop 插件配置外，将 VS Code 的 Files: Auto Save 从默认 off 改为 afterDelay 是关键操作之一。

检查是否设置成功

最简单的肯定是直接尝试是否会自动编译，自动保存

也可以找到设置json文件中出现新的一行：

 "files.autoSave": "afterDelay",