LaTeX Workshop 需正确配置根文件、ctex宏包、biber工具、-synctex=1参数及自动构建模式，否则xelatex静默失败、PDF不更新、同步失效；根文件须声明% !TEX root、禁用xeCJK、UTF-8编码.bib、recipe显式绑定biber、args含-synctex=1、autoBuild设onSave。
LaTeX Workshop 在 VS Code 中能支撑高质量学术论文排版，但前提是关键配置项必须对齐——错一个参数，xelatex 就会静默失败，PDF 不更新、终端不报错，你改了十遍代码也白搭。
根文件没识别，编译根本不会启动
VS Code 左下角状态栏必须显示 Root file: main.tex（或你实际的主文件名），否则插件连“编译谁”都不知道。常见原因有三个：
- 主文件里没加注释声明：% !TEX root = ./main.tex（注意用正斜杠
/，Windows 下也不能写\） -
latex-workshop.latex.rootFile手动设了路径，但写成相对路径错误，比如"./chapters/intro.tex"而不是"./main.tex" - 项目含子目录时，
% !TEX root注释没放在子文件顶部第一行，或被空行/其他注释挡住了
中文支持只用 ctex，别碰 xeCJK
中文论文必须用 xelatex 引擎，但宏包混用是高频翻车点。现在唯一稳定方案是：\usepackage{ctex} 一行搞定，不要手动加载 xeCJK。
- 混用
ctex和xeCJK会触发fontspec error: "font-not-found"，因为字体注册冲突 -
ctex已内置适配：Windows 默认找SimSun，macOS 用PingFang SC，Linux 用Noto Sans CJK SC - 如需微调字体，只改
ctex选项即可，例如：\usepackage[fontset=ubuntu]{ctex}
biber 替代 bibtex 是中文参考文献刚需
IEEE、ACM 或国标 GB/T 7714 模板下，bibtex 遇到中文作者名或 Unicode 期刊名直接崩溃；biber 是唯一可靠选择，但默认 recipe 不绑定它。
- 先确认
.bib文件编码为 UTF-8（无 BOM），VS Code 右下角要显示 “UTF-8” - 在
.vscode/settings.json中显式定义biber工具和 recipe：
{
"latex-workshop.latex.tools": [
{
"name": "biber",
"command": "biber",
"args": ["%DOCFILE%"]
}
],
"latex-workshop.latex.recipes": [
{
"name": "xelatex → biber → xelatex ×2",
"tools": ["xelatex", "biber", "xelatex", "xelatex"]
}
]
}
bibtex 配方，它不处理 UTF-8，也不兼容现代 bib 格式
-synctex=1 缺失会导致双向同步完全失效
点击 PDF 跳不到源码、悬停引用没反应，八成是编译命令里漏了 -synctex=1。这个参数不是可选，是 SyncTeX 正常工作的硬性前提。
- 检查当前 recipe 对应的
tools配置，确保每个xelatex或pdflatex的args包含"-synctex=1" - 如果用
latexmk，也要加"-synctex=1"，例如：["-synctex=1", "-pdf", "%DOC%"] - 编译后检查项目目录是否生成了
main.synctex.gz（main替换为你主文件名），没有就说明参数没生效
最易被忽略的是：所有这些配置都依赖 latex-workshop.latex.autoBuild.run 设为 onSave 或 onFileChange，设成 never 会导致整个自动流程瘫痪，而界面毫无提示。
