VSCode本身不编译LaTeX，仅调度xelatex、latexmk等系统工具；必须先在终端验证xelatex --version和latexmk --version能输出版本号，并确保PATH配置正确、插件显式指定xelatex引擎及-synctex=1参数。
VSCode 本身不编译 LaTeX，它只是调度器；真正出 PDF 的是系统里装的 xelatex、latexmk 这些命令——环境没配对，插件再全也白搭。
确认本地 TeX 工具链是否就位
这是所有问题的起点。VSCode 报 "xelatex not found" 或 "command not found"，90% 是这里卡住。
- 在终端（不是 VSCode 内置终端，先关掉它）运行：
xelatex --version和latexmk --version，必须都能输出版本号 - Windows：安装 TeX Live 时务必勾选 “Add TeX Live to PATH”；若漏了，手动把类似
C:\texlive\2024\bin\win32加进系统环境变量 - macOS：用
brew install --cask mactex（别用basictex，它默认不含latexmk）；装完后执行echo $PATH确认/Library/TeX/texbin在里面 - Linux：用
sudo apt install texlive-latex-recommended texlive-latex-extra latexmk，只装texlive-base不够 - VSCode 必须重启（不是重载窗口），才能读取新 PATH
LaTeX Workshop 编译配置必须显式指定 xelatex
默认 recipe 用的是 pdflatex，中文文档一编译就乱码或报错字体缺失——这不是插件 bug，是引擎选错了。
- 在 VSCode 设置中搜
latex-workshop.latex.recipes，点“在 settings.json 中编辑”，填入：
{
"latex-workshop.latex.recipes": [
{
"name": "xelatex",
"tools": ["xelatex"]
}
],
"latex-workshop.latex.tools": [
{
"name": "xelatex",
"command": "xelatex",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"%DOCFILE%"
]
}
]
}
-
%DOCFILE%是当前文件名（含路径），比%DOC%更可靠，尤其当主文档和子文件不在同一目录时 - 必须加
-synctex=1，否则 PDF 预览无法跳转回源码 - 别同时启用其他 LaTeX 插件（如 LaTeX Tools），会冲突
中文支持失效的三个硬性条件
光装 ctex 宏包没用，xelatex 找不到系统字体就会 fallback 到方块或死循环。
- 导言区必须写明字体，例如：
\setmainfont{Noto Serif CJK SC}（macOS/Linux）或\setmainfont{"Microsoft YaHei"}（Windows，带空格必须加引号） - 主 .tex 文件第一行加注释：
% !TEX root = main.tex，否则插件不认它是主文档，不会触发编译 - 如果项目放在 iCloud、OneDrive 或含中文/空格的路径下，
latexmk会直接报错Filename contains character not allowed for TeX file——换到纯英文无空格路径（如~/latex-paper）再试
PDF 不刷新、参考文献不更新、预览空白
这些表象背后，往往不是编译失败，而是构建流程没跑全或监听没生效。
- 首次含参考文献的编译，别依赖保存即编译（
onFileChange），手动按Ctrl+Alt+B（Win）或Cmd+Alt+B（Mac）至少跑两遍：xelatex → bibtex → xelatex - 内置 PDF 查看器容易卡死或不同步，设置里关掉
latex-workshop.view.pdf.viewer的tab模式，改用external（SumatraPDF / Skim） -
.bib文件路径要写对：\bibliography{refs}对应的是refs.bib，不是./bib/refs.bib——后者需写成\bibliography{bib/refs} - 检查
latex-workshop.latex.autoBuild.run是否设为onFileChange，但注意：它不监听.bib或子目录下的.tex变动
最常被忽略的一点：VSCode 的集成终端和系统终端 PATH 不一定一致，而插件调用命令时用的是前者。所以即使你在 iTerm 里能跑通 xelatex，VSCode 里仍可能报错——验证方式是打开 VSCode 内置终端，直接敲一遍命令。
