VSCode 编译 LaTeX 依赖系统已安装 xelatex 和 latexmk 并加入 PATH；需验证终端中两命令可用，正确配置 settings.json 中的 recipe 和 tools，指定主文件根路径，使用兼容 PDF 查看器并从终端启动 VSCode 以继承环境变量。
VSCode 本身不编译 LaTeX，能出 PDF 的唯一前提是：系统已装好 xelatex 和 latexmk，且它们在终端能直接调用；插件只是调度器，不是编译器。
终端先验证 xelatex --version 和 latexmk --version 是否可用
这是所有问题的起点。VSCode 报 “command not found” 或 “tool not found”，90% 是这里没过。
- macOS：用
brew install --cask mactex（别用basictex，它不含latexmk）；装完后确认/Library/TeX/texbin在$PATH中，比如在~/.zshrc里加export PATH="/Library/TeX/texbin:$PATH"，然后彻底重启 VSCode - Windows：安装 TeX Live 时必须勾选 “Add TeX Live to PATH”；若已装完，手动把类似
C: exlive4inwin32的路径加进系统环境变量，再重启 VSCode（不是重载窗口） - Linux：运行
sudo apt install texlive-latex-recommended texlive-latex-extra latexmk；只装texlive-base不够，latexmk会调不到bibtex - 验证方式：关掉 VSCode 内置终端，打开系统终端（Terminal / cmd / PowerShell），直接输
xelatex --version和latexmk --version——两个都必须有输出，才算真正就位
settings.json 里必须显式配 xelatex recipe 和 -synctex=1
默认 recipe 走 pdflatex，中文文档一编译就报字体缺失或乱码，这不是插件 bug，是引擎硬性不匹配。
- 按
Ctrl+Shift+P→ 输入 “Preferences: Open User Settings (JSON)” → 编辑settings.json - 至少填这两块：
"latex-workshop.latex.recipes"定义流程，"latex-workshop.latex.tools"定义命令 -
xelatex的args必须含-synctex=1，否则 PDF 预览无法跳转回源码 -
%DOCFILE%比%DOC%更可靠，尤其多级子目录时
{
"latex-workshop.latex.tools": [
{
"name": "xelatex",
"command": "xelatex",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"%DOCFILE%"
]
}
],
"latex-workshop.latex.recipes": [
{
"name": "xelatex",
"tools": ["xelatex"]
}
],
"latex-workshop.latex.recipe.default": "xelatex"
}
主文件第一行加 % !TEX root = main.tex 注释
LaTeX Workshop 默认不监听所有文件变动，尤其对 .bib、.sty 或子目录下的 .tex 文件静默忽略——它只认你指定的“主文档”。
- 哪怕只有一个
main.tex，也必须在第一行或前几行加上% !TEX root = main.tex - 检查设置里
latex-workshop.latex.autoBuild.run是onFileChange而不是never - 首次编译建议手动按
Ctrl+Alt+B（Win/Linux）或Cmd+Alt+B（macOS），别依赖保存即编译——有些模板（如IEEEtran）需要多遍跑bibtex才能出参考文献
PDF 不自动刷新？换用 Skim（macOS）或 SumatraPDF（Windows）
默认开启的 synctex 反向搜索（Ctrl+Click PDF 跳回源码）会锁住 PDF 文件，导致修改 .tex 后 PDF 不自动重载。
- Adobe Reader 或某些 PDF 查看器的行为限制，不是 bug
- 改用
Skim（macOS）或SumatraPDF（Windows），它们支持文件系统级热重载，且与 LaTeX Workshop 深度集成 - 设
latex-workshop.view.pdf.viewer为external，并填对查看器路径，例如 Windows 下设"latex-workshop.view.pdf.external.viewer.command": "C:\Program Files\SumatraPDF\SumatraPDF.exe" - 别碰
latex-workshop.view.pdf.internal.synctex.afterBuild.enabled这个开关——关了它虽能强制刷新，但会彻底失去点击跳转能力
最容易被忽略的是：VSCode 启动方式。如果从桌面图标启动，可能读不到 shell 中配置的 PATH；建议从终端运行 code . 启动，确保环境变量继承正确。
