vscode 不编译 latex，仅调用系统 xelatex 或 latexmk；95% 编译失败源于编译器未安装、path 配置错误或主文件未声明。需在系统终端验证工具路径，正确配置 latex workshop 的 xelatex 工具与 recipe，使用 ctex 文类并声明中文字体，添加 % !tex root 注释，确保 -synctex=1 及输出路径合规。
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 注释——这两处一错，整个编译链就断在起点，后面所有配置都无效。
