latexmk必须在终端可用，否则vs code无法调用编译器；需验证which latexmk和which xelatex均输出路径，再配置settings.json中tools、recipes及recipe.default三项，并用ctex类处理中文、声明root文件。
latexmk 必须在终端可用，否则 VS Code 根本调不动编译器——这不是插件问题，是系统 PATH 没对齐。所有“点不编”“预览空白”“报错 tool not found”的根源，90% 都卡在这一步。
确认 latexmk 和 xelatex 能被终端直接调用
LaTeX Workshop 插件只是个调度员，它不带编译器，只认系统 PATH 里注册的命令。
- 打开 VS Code 内置终端（
Ctrl+`），运行：which latexmk和which xelatex；两个都必须输出路径，缺一个就编译失败 - macOS 安装 MacTeX 后，
/Library/TeX/texbin很可能没进$PATH：在终端执行echo $PATH看有没有这个路径；没有就手动加到~/.zshrc末尾：export PATH="/Library/TeX/texbin:$PATH"，再source ~/.zshrc - Windows 用户安装 TeX Live 时若没勾选「Add to PATH」，需手动把类似
C:\texlive\2026\bin\win32加进系统环境变量，并重启 VS Code（不是重载窗口） - Linux 用户别只装
texlive-base，至少补上：sudo apt install texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra latexmk
settings.json 里必须配对的三个关键项
只装插件不改配置，等于买了车不给钥匙。以下三项必须同时存在、参数不能漏：
-
"latex-workshop.latex.tools"：定义工具，其中latexmk条目args必须含-synctex=1（否则 PDF 跳转失效）、-interaction=nonstopmode（避免卡在错误提示）、-xelatex（中文必需） -
"latex-workshop.latex.recipes"：定义配方，比如{"name": "latexmk (XeLaTeX)", "tools": ["latexmk"]}；名字随便写，但得和下一步匹配 -
"latex-workshop.latex.recipe.default"：设为上面配方的name值，例如"latexmk (XeLaTeX)"；不设或拼错，快捷键Ctrl+Alt+B就静默失败
中文编译必须用 ctex + XeLaTeX，别手写 fontspec
自己写 \usepackage{fontspec}\setmainfont{Noto Sans CJK SC} 容易因字体名大小写、系统缺失、路径空格等问题崩溃；ctex 是封装好的中文方案，稳定得多。
- 主文件第一行必须是：
\documentclass[UTF8]{ctexart}（或ctexrep/ctexbook），不能是article+ 手动加载宏包 - 导言区别再重复写
\usepackage{fontspec}或\usepackage{xeCJK}——ctex已内置，冲突会导致编译卡在 “Font T1/cmr/m/n/10=ecrm1000 at 10.0pt not loadable” - VS Code 右键 → “LaTeX Workshop: Select Recipe to Build”，选带
xelatex的配方；如果误选了pdflatex，中文直接变方块或报Package inputenc Error: Unicode char …
多文件项目不声明 root，\cite 和 \ref 全失效
VS Code 默认只编当前打开的 .tex 文件。如果你把章节拆成 ch1.tex、refs.bib，又没告诉插件哪个是主入口，参考文献和交叉引用就永远不生成。
- 在子文件顶部加注释：
% !TEX root = main.tex（路径相对当前文件）；或者在settings.json里全局指定："latex-workshop.latex.rootFile.useSubFile": false，再配合"latex-workshop.latex.rootFile.include"列出主文件名 - 修改了
.bib文件后，Ctrl+Alt+B必须按一次——自动保存编译（onSave）不会触发bibtex步骤，因为latexmk监听的是.tex文件变化 - PDF 预览打不开？先看状态栏右下角是否显示
LaTeX和当前引擎（如XeLaTeX）；不显示说明 root 未识别，插件根本没启动监听
latexmk 是否真在 PATH 里、root 文件是否被正确识别、以及 ctex 和 fontspec 别混用——这三处一错，其他配置全白搭。
