VSCode中LaTeX全自动编译需编译链、工具顺序与触发时机三者对齐，否则会出现引用显示??、空白PDF或bibtex报错；latexmk常失效因默认忽略.bbl更新，应改用显式recipe如["xelatex","biber","xelatex","xelatex"]并确保tools与recipes严格匹配。
VSCode里LaTeX论文写作能真正“全自动”，但前提是编译链、工具顺序和触发时机三者对齐；否则就会卡在??引用、空白PDF或bibtex报错上，不是插件问题，而是recipe没跑对。
为什么latexmk在VSCode里经常失效
latexmk本身是Perl脚本，依赖本地Perl环境和正确的.latexmkrc配置。VSCode的LaTeX Workshop默认启用它，但多数中文论文场景下它会跳过biber或误判.bib更新状态，导致参考文献不刷新。
- 典型症状：改了
\cite{}，保存后PDF里仍是[?]，终端日志却显示Latexmk: All targets (main.pdf) are up-to-date - 根本原因：
latexmk默认只监控.tex和.bib文件变动，但biber生成的.bbl被当成中间产物忽略，下次编译时直接复用旧.bbl - 实操建议：禁用
latexmk作为默认recipe，改用显式定义的tools数组顺序执行，比如["xelatex", "biber", "xelatex", "xelatex"] - 额外注意：
biber必须和biblatex配套使用；若文档用的是natbib+bibtex，则recipe里要换为bibtex，且顺序必须是xelatex → bibtex → xelatex → xelatex
settings.json里recipe和tool的参数怎么配才不踩坑
VSCode的LaTeX Workshop靠latex-workshop.latex.recipes和latex-workshop.latex.tools联动工作，二者必须严格对应——recipe里写的tool名，得在tools数组里真实存在，且args中%DOC%不能写成%DOCFILE%（后者会导致路径错误）。
- 关键参数差异：
-shell-escape必须加在xelatex的args里，否则minted代码块或fontspec调用系统字体会失败；-synctex=1决定PDF能否反向跳转，漏掉就失去SyncTeX功能 - Windows用户特别注意：
command值写"xelatex"即可，不要写"xelatex.exe"；VSCode会自动补全扩展名，硬写反而在Linux/macOS下报错 - macOS用户常见陷阱：
PATH未生效时，which xelatex返回空，此时settings.json里command需改为绝对路径，例如"/usr/local/texlive/2023/bin/universal-darwin/xelatex" - 推荐最小可用recipe示例（含中文支持）：
{ "name": "xelatex-biber", "tools": ["xelatex", "biber", "xelatex", "xelatex"] }
自动构建失败时，该看哪几行日志定位问题
LaTeX Workshop输出面板的日志不是线性流水账，真正有用的线索藏在三处：编译器启动行、工具退出码、以及最后一条=== TeX engine exited with code。
- 看到
spawn xelatex ENOENT：说明command路径不对，检查which xelatex输出，并确认settings.json里command值与之匹配 - 看到
Package biblatex Error: \addbibresource后跟文件未找到：不是.bib路径错，而是biber没被recipe调用，或者.bib文件名没加.bib后缀（\addbibresource{refs}应为\addbibresource{refs.bib}） - 看到
! LaTeX Error: File `ctex.sty' not found：TeX Live安装的是Basic版，缺中文宏包；运行tlmgr install ctex补装，而非重装整个发行版 - 交叉引用仍显示
??？检查.aux文件是否生成——若没有，说明第一次xelatex根本没跑成功，先解决前置错误再谈引用
自动化真正的难点不在配置项堆砌，而在于理解每个工具的输入/输出依赖：.aux是xelatex的输出、biber的输入；.bbl是biber的输出、xelatex的输入。漏掉任一环，链就断了。很多人反复重装插件，其实只是recipe里少写了一行"biber"。
