vscode+latex稳定运行需满足四个硬性条件：一、确保latexmk和xelatex在终端可用且path配置正确；二、中文支持必须用ctex宏包配合xelatex，主文件声明utf8编码；三、多文件项目须通过% !tex root注释或settings.json明确指定root文件；四、synctex反向跳转需查看器支持、编译参数含-synctex=1且使用新生成pdf。
编译失败、中文乱码、PDF不跳转、参考文献不显示——这些问题不是配置没到位，就是关键参数被忽略。VSCode + LaTeX 能跑起来不难，但要稳定支持学术写作（尤其是带 BibTeX、中文、多文件、SyncTeX 的长论文），必须卡准几个硬性条件。
确认 latexmk 和 xelatex 在终端可用
LaTeX Workshop 不会自己装编译器，它只调用系统 PATH 里的命令。如果终端里运行 latexmk --version 或 xelatex --version 报 “command not found”，VSCode 必定编译失败，且错误提示常是模糊的 “no recipe found” 或 “tool not found”。
常见情况：
- macOS 安装 MacTeX 后未把
/Library/TeX/texbin加入$PATH（尤其用brew install --cask mactex安装后需手动补） - Windows 安装 TeX Live 时没勾选 “Add TeX Live to PATH”，或安装完没重启 VSCode
- Linux 用户只装了
texlive-base，缺latexmk和lualatex/xelatex包
验证方式：在 VSCode 内置终端（Ctrl+`）中直接运行 which latexmk 和 which xelatex，两个都必须有输出。没有？先解决系统级路径，再动 VSCode 设置。
ctex + XeLaTeX 是中文论文最稳组合
用 \usepackage{xeCJK} 或手写 \setmainfont 很容易漏掉依赖或字体名拼错；而 ctex 宏包封装了编码、字体、章节样式、页眉页脚等一整套中文适配逻辑，配合 XeLaTeX 引擎基本零配置就能出效果。
实操要点：
- 主文件第一行必须是
\documentclass[UTF8]{ctexart}（或ctexrep/ctexbook），不能是article+ 手动加xeCJK - VSCode 中右键编辑器空白处 → “LaTeX Workshop: Select Recipe to Build” → 选含
xelatex的 recipe（如xelatex单步，或xelatex -> bibtex -> xelatex*2） - 确保
settings.json里latex-workshop.latex.tools中xelatex的args包含-synctex=1和-interaction=nonstopmode - 不要在导言区重复加载
fontspec或xeCJK——ctex已内置，冲突会导致编译卡住或报fontspec error
多文件项目必须声明 root 文件，否则 bibtex 和 ref 全失效
VSCode 默认只认当前打开的 .tex 文件为编译目标。如果你把引言、方法、实验拆成 intro.tex、method.tex 等，又没告诉 LaTeX Workshop 哪个是主文件，它就会对 \cite{}、\ref{}、\bibliography{refs} 视而不见，编译出来的 PDF 满篇 “??”。
正确做法只有两种（任选其一）：
- 在每个子文件顶部加注释：
% !TEX root = main.tex（main.tex是你的主文件名） - 在项目根目录建
.vscode/settings.json，写入："latex-workshop.latex.rootFile.enabled": true，并确保主文件名是main.tex或显式设"latex-workshop.latex.rootFile": "paper.tex"
注意：% !TEX root 注释必须是文件**第一行**，前面不能有空行或 BOM；且所有 \input{} 或 \include{} 路径要相对于主文件位置，不是相对于子文件。
SyncTeX 反向跳转失效？检查三个地方
Cmd/Ctrl + Click PDF 文本没反应，或者跳转到错行，大概率不是插件问题，而是编译链或查看器没对齐。
必须同时满足：
-
latex-workshop.view.pdf.viewer设为"tab"（内建查看器）或"external"（外部如 Skim / SumatraPDF），不能是"none" -
xelatex工具的args中包含-synctex=1（不是-synctex=-1或漏掉） - PDF 查看器本身支持 SyncTeX：Skim（macOS）需开启 “Preferences → Sync → Check for file changes”；SumatraPDF（Windows）默认支持；VSCode 内建查看器无需额外设置，但要求 PDF 是本次编译生成的（旧 PDF 不带 synctex 数据）
最容易被忽略的是：改完 settings.json 后没重新触发编译 —— Synctex 信息只写在当次生成的 PDF 里，旧 PDF 不会自动更新。
真正卡住人的从来不是“怎么装”，而是某个路径没生效、某行注释位置错了、某个宏包被重复加载。这些点不逐个验过，光靠复制粘贴配置，十有八九会在编译第 3 次时突然崩在 biber 或 undefined control sequence 上。
