vscode 的 latex workshop 插件需系统已安装并配置好 tex 发行版（如 tex live/mactex），确保 xelatex、latexmk、bibtex 在 path 中；多文件项目须在子文件首行加 % !tex root = main.tex；中文推荐用 ctex 宏包配合 xelatex；编译链需含 -synctex=1 和显式 bibtex 步骤。
VSCode 能跑 LaTeX 编译和预览，但前提是系统 PATH 里真有 latexmk、xelatex 和 bibtex ——插件只是调度器，不是编译器。
终端能跑 xelatex --version 吗？不能就别进 VSCode
LaTeX Workshop 不会帮你装 TeX 发行版，它只调用你系统 PATH 中已有的命令。Windows 装 TeX Live 时没勾选 “Add TeX Live to PATH”，或 macOS 安装 MacTeX 后没把 /Library/TeX/texbin 加进 $PATH，VSCode 内置终端里运行 which xelatex 或 where latexmk 就会返回空。此时点击编译，错误提示常是模糊的 "No recipe found" 或 "Tool not found"。
- 验证方式：在 VSCode 内置终端（
Ctrl+`）中依次执行which xelatex、which latexmk、which bibtex，三个都必须有输出 - Windows 手动加 PATH 示例：
C:\texlive\2024\bin\win32；macOS 建议在~/.zshrc里追加export PATH="/Library/TeX/texbin:$PATH" - 改完 PATH 必须重启 VSCode，否则设置不生效
% !TEX root = main.tex 必须写在子文件第一行
多文件项目（比如把引言、方法、实验拆成 intro.tex、method.tex）时，LaTeX Workshop 默认只认当前打开的文件为编译目标。如果你在 method.tex 里按 Ctrl+Alt+B，它不会去找 \bibliography{refs} 或 \include{intro}，结果参考文献全显示 ??，交叉引用失效。
- 解决办法：在每个子文件顶部第一行加上注释
% !TEX root = main.tex（路径相对主文件，支持../main.tex） - 或者统一在
settings.json里配"latex-workshop.latex.rootFile.useSubFile": false，强制以打开的文件所在目录下第一个.tex为根（不推荐，易误判） - 注意：这行注释必须是文件最开头，前面不能有空行或 BOM 字符
中文编译必须用 ctex + xelatex，别手写 xeCJK
用 \usepackage{xeCJK} 配中文字体，容易漏掉编码声明、字体路径、标点挤压等细节；而 ctex 宏包封装了整套中文适配逻辑，配合 xelatex 引擎基本零配置就能出效果。
- 主文件第一行必须是
\documentclass[UTF8]{ctexart}（或ctexrep/ctexbook），不能是article+ 手动加载xeCJK - Windows 推荐字体名用引号包裹：
\setmainfont{"SimSun"}或\setmainfont{"Microsoft YaHei"}，避免空格解析失败 - macOS/Linux 可直接用
Noto Serif CJK SC，但需确认系统已安装该字体（fc-list | grep "Noto"）
latexmk 编译链里 -synctex=1 和 bibtex 顺序不能错
参考文献不显示、PDF 点击跳转不到源码，大概率是编译参数缺失或步骤错乱。latexmk 是推荐的自动化工具，但它默认不启用 SyncTeX，也不自动调用 bibtex 处理 .bib 文件。
- 确保
settings.json中xelatex的args包含"-synctex=1"和"-interaction=nonstopmode" - recipe 必须显式包含
bibtex步骤，例如："xelatex -> bibtex -> xelatex*2"；只跑一遍xelatex，参考文献字段永远是?? - PDF 查看器建议设为
external（如 SumatraPDF / Skim），VSCode 内置 tab 模式常卡住不刷新，尤其在修改.bib后
最容易被忽略的是：编译器路径、主文件声明、SyncTeX 参数、bibtex 调用顺序，这四个点只要一个没对齐，就会表现为“能编译但内容不对”。别急着调插件设置，先在终端里把 latexmk -xelatex main.tex 跑通再说。
