vscode本身不编译latex，出pdf的前提是系统已安装xelatex和latexmk且终端可调用；必须先验证xelatex --version和latexmk --version有输出，再在settings.json中显式配置xelatex引擎及-synctex=1参数。
VSCode 本身不编译 LaTeX，能出 PDF 的唯一前提是：系统里装好了 xelatex 和 latexmk，且它们在终端能直接调用；插件只是调度器，不是编译器。
终端先跑通 xelatex --version 和 latexmk --version
这是所有问题的起点。VSCode 报 “command not found” 或 “tool not found”，90% 是这里没过。
- Windows：安装 TeX Live 时必须勾选 “Add TeX Live to PATH”；漏了就手动把类似
C: exlive4inwin32加进系统环境变量，然后彻底重启 VSCode（不是重载窗口） - 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不够，latexmk会调不到bibtex或makeindex - 验证方式：关掉 VSCode 内置终端，打开系统终端（Terminal / cmd / PowerShell），直接输
xelatex --version和latexmk --version—— 两个都必须有输出，才算真正就位
settings.json 里必须显式配 xelatex 引擎和 -synctex=1
LaTeX Workshop 默认 recipe 走 pdflatex，中文文档一编译就报字体缺失或乱码，这不是插件 bug，是引擎选错了。
- 在 VSCode 中按
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.recipes": [
{
"name": "xelatex",
"tools": ["xelatex"]
}
],
"latex-workshop.latex.tools": [
{
"name": "xelatex",
"command": "xelatex",
"args": [
"-synctex=1",
"-interaction=nonstopmode",
"-file-line-error",
"%DOCFILE%"
]
}
]
}
中文论文必须用 ctex 类 + XeLaTeX，且主文件第一行加注释
光装 ctex 宏包不够，xelatex 找不到系统字体就会 fallback 成方块，甚至卡死在日志里反复报 Font zf@basefont= not loadable。
- 主
.tex文件第一行必须是documentclass[UTF8]{ctexart}（或ctexrep/ctexbook），不能是article+ 手动加xeCJK - 导言区不用再写
usepackage{fontspec}或setmainfont——ctex已封装默认中文字体链，Windows 用 “Microsoft YaHei”，macOS/Linux 用 “Noto Serif CJK SC” - 必须在主文件顶部加注释：
% !TEX root = main.tex（哪怕就一个文件，也得写），否则插件不认它是根文档，cite、ibliography全失效 - 保存文件时务必用 UTF-8 编码，VSCode 右下角状态栏点编码名可切换；存成 GBK 会直接报
Package inputenc Error: Unicode char …
PDF 不自动刷新？换外部查看器 + 关 tab 模式
VSCode 内置 PDF 查看器（tab 模式）在启用 SyncTeX 时会锁住文件，导致修改后 PDF 不重载 —— 这不是 bug，是设计限制。
- Windows 用户装
SumatraPDF，macOS 用户装Skim，它们支持文件系统级热重载，且与 LaTeX Workshop 深度集成 - 在
settings.json中设："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这个开关——关了它虽能强制刷新，但反向跳转（Ctrl+Click PDF）就彻底失效 - 首次编译建议手动按
Ctrl+Alt+B（Win/Linux）或Cmd+Alt+B（macOS），别依赖保存即编译；像 IEEEtran 这类模板需多遍跑bibtex才能出参考文献
最常被忽略的是：PATH 修改后没重启 VSCode、主文件没加 % !TEX root 注释、以及误用 pdflatex 引擎编译中文文档 —— 这三处卡住，其他配置再全也白搭。
