VSCode 编译 LaTeX 失败需依次安装 TeX Live、配置 LaTeX Workshop 扩展、设置根文件与输出路径、启用 xeCJK 中文支持、规范 BibLaTeX 编译流程。
如果您使用 VSCode 编辑 LaTeX 文档，但无法正确编译、预览或自动补全数学公式，则可能是由于扩展配置缺失、编译链未指定或 LaTeX 发行版未安装。以下是解决此问题的步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、安装 LaTeX 发行版与核心工具
VSCode 本身不包含 LaTeX 编译器，必须依赖系统级 LaTeX 环境才能生成 PDF。缺少 TeX Live 或 MiKTeX 将导致所有编译命令失败。
1、访问 https://www.tug.org/texlive/ 下载 TeX Live 安装程序。
2、运行安装脚本，勾选 full scheme 并确保包含 latexmk 和 biber 工具。
3、安装完成后，在终端执行 latex --version 验证是否返回版本信息。
二、配置 LaTeX Workshop 扩展
LaTeX Workshop 是 VSCode 中功能最完整的 LaTeX 插件，提供实时编译、反向搜索、结构导航与引用检查。未启用该扩展将无法触发任何自动化排版流程。
1、在 VSCode 扩展市场中搜索 LaTeX Workshop 并点击安装。
2、打开 VSCode 设置（Cmd + ,），搜索 latex-workshop.latex.recipes，点击“编辑 in settings.json”。
3、在数组中添加以下配方：
{"name": "latexmk", "tools": ["latexmk"]}
三、设置默认编译器与输出路径
LaTeX Workshop 默认不自动选择编译器，需手动指定主文件与输出目录，否则会报错“no root file detected”或生成 PDF 到错误位置。
1、在项目根目录创建 .vscode/settings.json 文件。
2、写入以下内容：
{"latex-workshop.latex.rootFile.enabled": true, "latex-workshop.latex.outDir": "./_output"}
3、在项目中新建一个以 .tex 结尾的文件，并在首行添加注释 % !TEX root = main.tex。
四、启用中文支持与字体配置
默认 LaTeX 模板不支持中文，直接输入汉字会导致编译中断或显示方块。需通过 CJK 或 xeCJK 宏包配合 XeLaTeX 引擎实现 Unicode 字体渲染。
1、在导言区加载 \usepackage{xeCJK} 并设定中文字体：
\setmainfont{Times New Roman}\setCJKmainfont{Noto Serif CJK SC}
2、将编译器切换为 xelatex：右键编辑器空白处，选择 “LaTeX Workshop: Select Recipe to Build” → “xelatex”。
3、确保系统已安装 Noto Serif CJK SC 或其他支持简体中文的 OpenType 字体。
五、修复参考文献无法生成的问题
BibTeX 或 BibLaTeX 引用条目无法出现在 PDF 中，通常源于 .bib 文件路径错误、引用命令未触发后处理或 cite 命令格式不匹配。
1、确认 .bib 文件与主文档位于同一目录，或在 \addbibresource{} 中填写相对路径。
2、使用 BibLaTeX 时，确保导言区包含：
\usepackage[backend=biber,style=numeric]{biblatex}
3、编译顺序必须为：xelatex → biber → xelatex → xelatex；可在 recipes 中定义多步流程。
