vscode运行latex需系统级工具链就位、主文件明确声明、中文引擎参数完整；缺一即致“no recipe found”或空白预览。latexmk“command not found”因path未配置，须在终端验证which/where latexmk并修正path；pdf不刷新需添加% !tex root注释、启用autobuild.onfilechange、改用external查看器；中文乱码须用ctex文档类+utf8编码，必要时显式\setmainfont并加引号。
VSCode 能跑 LaTeX 编译和 PDF 预览，但前提是系统级工具链就位、主文件声明明确、中文引擎参数不漏——缺一不可，否则只会卡在“no recipe found”或空白预览页。
latexmk 报 “command not found” 怎么办
这不是插件没装好，而是 VSCode 根本找不到 latexmk 这个命令。LaTeX Workshop 只是调度器，不自带编译器。
- 先在终端（VSCode 内置终端也行）运行
which latexmk（macOS/Linux）或where latexmk（Windows），必须有输出；没有就说明 TeX 发行版没装，或 PATH 没配对 - macOS 用
brew install --cask mactex后，需手动把/Library/TeX/texbin加进 shell 的$PATH（比如~/.zshrc里加export PATH="/Library/TeX/texbin:$PATH"），然后重启 VSCode - Windows 安装 TeX Live 时务必勾选 Add TeX Live to PATH；若已安装完，就手动把类似
C:\texlive\2024\bin\win32的路径加进系统环境变量 - Ubuntu/Debian 用户别只装
texlive-base，得装sudo apt install texlive-latex-recommended texlive-latex-extra latexmk
PDF 不自动刷新或预览窗口空白
LaTeX Workshop 默认不监听所有文件变动，尤其对 .bib、.sty 或子目录下的 .tex 文件静默忽略——它只认你指定的“主文档”。
- 在主
main.tex文件第一行或前几行加上注释：% !TEX root = main.tex（哪怕就是本文件，也必须写） - 检查设置里
latex-workshop.latex.autoBuild.run是onFileChange而不是never - 关掉内置 PDF 查看器的 tab 模式：设
latex-workshop.view.pdf.viewer为external，并配好外部查看器（macOS 用 Skim，Windows 用 SumatraPDF） - 首次编译建议手动按
Ctrl+Alt+B（Win/Linux）或Cmd+Alt+B（macOS），别依赖保存即编译——有些模板（如 IEEEtran）需要多遍跑bibtex才能出参考文献
中文显示方块、编译卡在 xelatex 或字体报错
现代中文 LaTeX 写作基本锁定 xelatex + ctex，但漏掉字体显式声明或编码声明，就会 fallback 到缺字状态甚至死循环。
- 主文件第一行必须是
\documentclass[UTF8]{ctexart}（或ctexrep/ctexbook），不能用article+ 手动加xeCJK - 导言区不用手写
\setmainfont，ctex已封装默认中文字体逻辑；但如果系统没注册对应字体（如 macOS 缺Noto Serif CJK SC），就得手动补：加一行\setmainfont{"Noto Serif CJK SC"}（注意带引号，空格必须包裹） - Windows 推荐用
"SimSun"或"Microsoft YaHei"，但引号不能少，否则xelatex解析失败 - 确保
latex-workshop.latex.tools中xelatex的args包含-synctex=1和-interaction=nonstopmode
多文件项目里 \cite{} 显示 ??、参考文献不出现
VSCode 默认只把当前打开的 .tex 文件当编译目标。如果你拆了 intro.tex、method.tex，又没告诉 LaTeX Workshop 哪个是主文件，\bibliography{refs} 就会被完全跳过。
- 必须在每个被
\input{}或\include{}引入的子文件顶部，也加上% !TEX root = main.tex - 确认
main.tex里调用了\bibliography{refs}（路径相对主文件），且refs.bib真的存在 - 检查
latex-workshop.latex.recipe.default设为latexmk，且latexmk配方里启用了bibtex或biber步骤（默认通常已包含） - 编译日志里如果看到
There were undefined references，别急着改源码，先手动清掉.aux、.bbl等中间文件再重编一次
最常被跳过的其实是 % !TEX root 声明和系统级 PATH 验证——这两步没做，后面所有配置都只是在调试一个根本不会启动的流程。
