VSCode需扩展与外部工具链协同编译LaTeX；必须安装LaTeX Workshop及系统级编译器（如MiKTeX、MacTeX或TeX Live），正确配置latex-workshop.latex.recipes和PDF预览器路径，否则易出现“No PDF viewer connected”等错误。
VSCode 本身不支持 LaTeX 编译，必须靠扩展和外部工具链协同工作；配错一个环节（比如 latexmk 路径、recipe 顺序、或 settings.json 中的 latex-workshop.latex.recipes）就会卡在「No PDF viewer connected」或「Cannot find root file」这类错误里。
安装必要扩展与系统级依赖缺一不可
只装 LaTeX Workshop 扩展是没用的——它只是调度器，背后需要真正的编译器。Windows 用户常误以为装了 MiKTeX 就万事大吉，但默认不勾选「Add MiKTeX to PATH」，导致 VSCode 根本找不到 latexmk 或 pdflatex。
- macOS：用
brew install --cask mactex（完整版）或brew install latexmk+tectonic（轻量替代），确保which latexmk有输出 - Windows：安装 MiKTeX 时务必勾选「Add MiKTeX to PATH for all users」，或手动把
C:Program FilesMiKTeXmiktexind加进系统环境变量 - Linux：安装
texlive-full（Ubuntu/Debian）或texlive-most（Arch），再单独sudo apt install latexmk - 验证：终端运行
latexmk -v，不是「command not found」才算过关
latex-workshop.latex.recipes 必须显式配置编译流程
新版 LaTeX Workshop 默认禁用自动 recipe 推荐，不手动配 recipes，点「Build LaTeX project」就直接报错「No recipe to build」。很多人抄网上配置却忽略自己本地实际可用的命令——比如用了 tectonic 却没装，或写了 lualatex 但系统只有 pdflatex。
- 最简可靠 recipe（兼容多数场景）：
[ { "name": "latexmk", "tools": ["latexmk"], "args": ["-pdf", "-shell-escape", "-synctex=1", "%DOC%"] } ] -
"%DOC%"是占位符，代表当前打开的.tex文件；若项目含子文件（如main.tex包含ch1.tex），需在main.tex顶部加注释% !TEX root = main.tex - 不用
latexmk？可改用pdflatex工具链，但要额外配tools数组和依赖顺序（如先pdflatex→bibtex→ 再两次pdflatex）
PDF 预览失效的三个高频原因
「Build」成功但右下角没弹出 PDF 预览，或预览空白，大概率不是插件问题，而是路径、权限或 viewer 配置冲突。
- 检查
latex-workshop.view.pdf.viewer：设为"tab"（内建 tab 预览）最稳；设"external"时，latex-workshop.view.pdf.external.viewer.command必须填绝对路径（如"C:\Program Files\SumatraPDF\SumatraPDF.exe"），且不能带空格未转义 - macOS 上预览器用
Skim时，必须在 Skim 设置中勾选「Check for file changes」，否则编辑保存后 PDF 不自动刷新 - Linux 下若用
evince，需确认已安装evince-previewer（Ubuntu）或启用 D-Bus 支持，否则无法响应 VSCode 的同步跳转请求 - 所有平台：PDF 文件被其他程序独占锁定（比如用 Adobe Acrobat 手动打开了），会导致预览失败且无明确报错
真正卡住人的从来不是「怎么配」，而是「哪一层出了问题」——是 latexmk 没找到，还是 root 没声明，或是 PDF viewer 权限被系统拦截。建议从终端手动跑一遍 latexmk -pdf main.tex，再对照 VSCode 输出面板里的 LaTeX Compiler Log 逐行比对路径和错误码。
