vscode 编译 latex 依赖系统工具链，95% 失败源于工具链配置错误、path 未生效或主文件未声明；须在原生命令行验证 xelatex/latexmk 可用性，并正确配置 ctex + xelatex 工具链与主文档标记。
VSCode 本身不编译 LaTeX，所有 PDF 都是靠系统里 xelatex、latexmk 这类命令生成的；插件只是调度器。配错工具链、PATH 没生效、主文件没声明——这三类问题占编译失败的 95%，而不是插件装得不够多。
确认 xelatex 和 latexmk 能在终端直接调用
这是硬前提。VSCode 内置终端（Ctrl+`）不是验证环境的可靠方式，它可能继承了错误的 PATH。必须在系统原生命令行中验证：
- Windows：打开
cmd，运行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后，要确认/Library/TeX/texbin在$PATH里，否则echo $PATH看不到就得补
在 settings.json 中显式配置 xelatex 工具与 recipe
LaTeX Workshop 默认 recipe 是 pdflatex，中文文档一跑就缺字体或乱码。必须手动覆盖，且参数不能少：
-
latex-workshop.latex.tools中定义xelatex工具，args至少包含：-synctex=1（否则 PDF 无法跳回源码）、-interaction=nonstopmode（避免卡死）、-file-line-error（精确定位报错行）、%DOCFILE%（比%DOC%更稳，尤其多级子目录时） -
latex-workshop.latex.recipes中定义一个只含xelatex的 recipe，名字随意，但别叫pdflatex - 不要同时启用
LaTeX Tools或其他 LaTeX 插件，会抢编译控制权，导致静默失败 - 如果项目含参考文献，建议额外配一个
latexmkrecipe，args加上-xelatex和-pdf，让latexmk自动决定是否跑bibtex
中文支持失效，八成是导言区和主文件声明没对齐
ctex 宏包 + xelatex 是目前最稳组合，但必须满足三个条件才真正生效：
- 主
.tex文件第一行必须是\documentclass[UTF8]{ctexart}（或ctexrep/ctexbook），不能是article+ 手动加载xeCJK - 主文件顶部必须加注释：
% !TEX root = main.tex（哪怕就一个文件，也得写）；否则插件不认它是入口，\cite{}、\ref{}全失效 - 系统字体必须存在且名字拼对：
Microsoft YaHei（Windows，带空格要加引号）、Noto Serif CJK SC（macOS/Linux），不能只写Noto Sans CJK——后者在 TeX Live 里默认不带 - 别在导言区重复
\usepackage{fontspec}或\usepackage{xeCJK}，ctex已内置，冲突会导致fontspec报错或编译挂起
PDF 不刷新、引用显示 ??、SyncTeX 跳转失败
这些问题几乎都指向同一个底层机制：LaTeX Workshop 不监听所有文件变动，它只信任你明确指定的“主文档”及其编译流程。
- 修改了
.bib文件？必须手动按Ctrl+Alt+B（Win/Linux）或Cmd+Alt+B（macOS）触发一次构建；保存.tex不会自动拉bibtex - PDF 预览空白或不更新？先关掉
latex-workshop.view.pdf.viewer: "tab"，改用"external"，并确保外部阅读器（如 SumatraPDF / Skim）支持 SyncTeX - 点击 PDF 无法跳回源码？检查三点：
-synctex=1是否在xelatex的args里、PDF 是最新编译生成的、查看器是用Ctrl+Alt+V（Win）或Cmd+Alt+V（macOS）从 VSCode 启动的，不是双击打开的 - 交叉引用始终显示
??？不是代码写错了，是没跑够遍数——latexmk会自动处理，但如果你只用单步xelatex，就得手动跑两遍
最易被忽略的是：VSCode 不会自动识别多文件项目的结构，它只看当前打开的文件。哪怕你写了 \input{ch1.tex}，只要没在 ch1.tex 顶部加 % !TEX root = main.tex，它就永远不会参与编译流程。
