VSCode 本身并不编译 LaTeX，它只是调用你系统里装好的 xelatex 或 latexmk。环境没通，插件装得再全也白搭——95% 的“点编译没反应”“PDF 出不来”“中文变方框”，都卡在同一个地方：编译器没装、PATH 没配对，或者主文件没声明。这三件事，任何一件没到位，整个编译链就断在起点，后面所有配置都成了摆设。
确认 xelatex 和 latexmk 能在终端直接运行
别信 VSCode 内置终端（Ctrl+`），它可能继承了错误的 PATH。必须用系统原生命令行验证：
- Windows：打开
cmd或PowerShell，运行where xelatex和where latexmk，两个都得输出路径。 - macOS/Linux：打开 Terminal，运行
which xelatex和which latexmk，不能返回空。 - 若任一命令报
command not found，说明 TeX 发行版没装全，或 PATH 没加对——此时改 VSCode 设置毫无意义。 - Windows 安装 TeX Live 时如果漏选了“Add TeX Live to PATH”，需要手动把类似
C:\texlive\2026\bin\win32加进系统环境变量；加完之后必须完全退出 VSCode 再重开。 - macOS 用
brew install --cask mactex后，检查echo $PATH是否包含/Library/TeX/texbin；没有就得补上。
在 settings.json 中显式定义 xelatex 工具和 recipe
LaTeX Workshop 默认用 pdflatex，中文文档一跑就挂——不是插件问题，是引擎根本不对。必须手动覆盖：
latex-workshop.latex.tools里定义xelatex工具，args至少包含：-synctex=1（否则 PDF 点击跳不回源码）、-interaction=nonstopmode（避免卡死）、-file-line-error（精确定位报错行）、%DOCFILE%（比%DOC%更稳，尤其多级子目录）。latex-workshop.latex.recipes中定义一个只含xelatex的 recipe，名字随意（如"XeLaTeX"），但别叫pdflatex。latex-workshop.latex.recipe.default设为该 recipe 名，例如"XeLaTeX"。- 如果项目含参考文献，建议额外加一个
latexmkrecipe，args加上-xelatex和-pdf，让latexmk自动决定是否跑bibtex。
documentclass 必须用 ctexart 或 ctexrep，且首行带 [UTF8]
光装 ctex 宏包没用；xelatex 找不到系统字体就会 fallback 成方块，甚至死循环编译：
- 主
.tex文件第一行必须是\documentclass[UTF8]{ctexart}（论文用）或{ctexrep}（报告用），不能是article+ 手动加xeCJK。 - 导言区显式声明中文字体：
\setmainfont{Noto Serif CJK SC}（macOS/Linux），或\setmainfont{"Microsoft YaHei"}（Windows，带空格必须加引号）。 - 主文件顶部加注释：
% !TEX root = main.tex（哪怕就一个文件，也得写）；否则插件不认它是入口，\cite{}、\ref{}全失效。 - 别重复加载
fontspec或xeCJK——ctex已内置，冲突会导致字体加载失败。
PDF 预览失效？重点查 -synctex=1、输出路径和 viewer 配置
VS Code 内置 PDF 查看器依赖 synctex 信息，而这个信息必须由编译器生成，且路径不能被拦截：
- 确认编译命令含
-synctex=1参数（上面xelatex示例已包含）。 - PDF 输出路径不能跨盘符或含空格/中文——比如
D:\My Papers\thesis.pdf可能触发安全限制，建议用默认./out/目录。 - 如果用外部阅读器（如 SumatraPDF），需额外配置
latex-workshop.view.pdf.external.viewer.command，且必须关闭其「只允许一个实例」选项，否则反向同步（Ctrl+Click跳回源码）会失败。
最常被忽略的是：改完 PATH 后没重启 VSCode，或主文件没加 % !TEX root 注释——这两处一错，整个编译链就断在起点，后面所有配置都无效。
