直接结论：vscode + latex workshop 配置核心是 latexmk 管编译、ctex 统中文、-synctex=1 拉通源码与 pdf；三者未对齐则 pdf 不更新且无报错，主因常为 root 文件未识别、路径用反斜杠、错误提示被关闭、中英文混排宏包冲突、参考文献误用 bibtex、synctex 参数缺失或路径编码不规范。
直接结论：VSCode + LaTeX Workshop 的配置核心不是“装插件”，而是让 latexmk 管住编译流程、用 ctex 统管中文、靠 -synctex=1 拉通源码与 PDF——三者没对齐，其他优化全是空谈。
为什么 xelatex 编译后 PDF 不更新，还看不到错误？
这是最常卡住人的第一道坎。现象是右下角闪一下 “Building…” 就消失，PDF 标签页静止不动，终端也无报错。
-
latex-workshop.latex.autoBuild.run被设为"never"或"onSave"，但你主文件没被识别为 root —— 左下角没显示Root file: main.tex就等于插件根本不知道编译谁 - 手动指定
latex-workshop.latex.rootFile时用了反斜杠（如".\main.tex"），Windows 下也必须用正斜杠："./main.tex" - 子文件（如
chapters/intro.tex）里缺了顶部注释：% !TEX root = ../main.tex，导致插件无法向上追溯 -
latex-workshop.message.error.show被关掉，编译失败日志被吞掉；临时打开它，终端里才能看到! Undefined control sequence或fontspec error: "font-not-found"
中英文混排该用 ctex 还是 xeCJK？
别混用。现在唯一稳定方案是只加载 ctex，一行搞定：\usepackage{ctex}。
- 手动加
xeCJK再套ctex，会触发字体重复注册，XeLaTeX 直接报fontspec error: "font-not-found" -
ctex已内置适配：Windows 默认用SimSun，macOS 用PingFang SC，Linux 用Noto Sans CJK SC，无需显式声明 - 真要微调字体，改
ctex选项即可，比如：\usepackage[fontset=ubuntu]{ctex}（Ubuntu 系统）或[fontset=macos] - 标点挤压、段落缩进异常、章节标题乱码，90% 是因为混用了宏包，删掉所有
xeCJK相关代码，只留ctex即可解决
参考文献该配 bibtex 还是 biber？
中文作者名、Unicode 期刊名、GB/T 7714 等国标模板，必须用 biber；bibtex 只吃 ASCII，遇到中文就跪。
-
.bib文件编码必须是 UTF-8（无 BOM）—— VS Code 右下角状态栏确认，不是 ANSI 或 GBK - 在
settings.json中定义biber工具，并替换 recipe："name": "xelatex → biber → xelatex ×2"，对应tools数组为["xelatex", "biber", "xelatex", "xelatex"] - LaTeX Workshop 默认 recipe 绑死
bibtex，不手动改就永远走不通中文参考文献 -
biber需要 Perl 环境，TeX Live 2024+ 自带；若提示Can't locate Biber.pm，说明 Perl 没装或路径没进 PATH
正反向同步（SyncTeX）为什么双击 PDF 跳不回代码？
关键不在 PDF 查看器，而在三个参数是否同时生效：-synctex=1、latex-workshop.view.pdf.external.viewer.command、反向搜索命令。
-
-synctex=1必须出现在xelatex或latexmk的args里，缺了它 SyncTeX 就是摆设 - 用 SumatraPDF 作外部阅读器时，
latex-workshop.view.pdf.external.viewer.command要指向真实 exe 路径，例如："C:/App/SumatraPDF/SumatraPDF.exe" - 反向搜索命令必须严格写成：
"-inverse-search", "code -r -g \"%f:%l\""——%f和%l是占位符，不能漏引号，也不能写成%F或%L - VS Code 启动必须用命令行
code（而非桌面快捷方式），否则-r -g参数无法被识别，双击后打不开编辑器
最容易被忽略的其实是路径和编码：所有项目路径不能含中文或空格，.bib 文件必须 UTF-8（无 BOM），settings.json 里的路径一律用正斜杠。这些细节不处理，再好的配置也跑不起来。
