VSCode需配合LaTeX Workshop插件与本地TeX发行版（如TeX Live/MiKTeX）才能完成LaTeX全流程；缺任一环节会导致保存无反应、快捷键无效、PDF不更新等问题。
VSCode 本身不直接编译 LaTeX，必须配合 LaTeX Workshop 插件 + 本地 TeX 发行版（如 TeX Live 或 MiKTeX）才能完成编写、编译、预览全流程。缺任一环节都会卡在「点保存没反应」「快捷键无效」「PDF 不更新」这类问题上。
安装并配置 LaTeX Workshop 插件
这是 VSCode 中最成熟、维护活跃的 LaTeX 支持插件。它不自带编译器，只负责调用系统已有的 pdflatex、xelatex 等命令。
- 在 VSCode 扩展市场搜索
LaTeX Workshop，安装后重启编辑器 - 确保插件启用：打开命令面板（
Ctrl+Shift+P），输入LaTeX: Open Settings (JSON)，确认没有禁用相关配置项 - 插件默认会自动探测系统 PATH 中的
latexmk或pdflatex；若未识别，需手动指定路径——例如 Windows 下 MiKTeX 安装后，latexmk通常位于C:\miktex\miktex\bin\x64\，需在设置中填入"latex-workshop.latex.tools": [...]并补全args和command - 不要勾选「Use internal PDF viewer」以外的第三方 PDF 查看器（如 SumatraPDF）除非你明确需要反向同步；否则容易因权限或路径空格导致编译后无法自动刷新
验证本地 TeX 发行版是否就绪
VSCode 和插件只是“指挥官”，真正干活的是你电脑上装的 TeX 引擎。很多用户跳过这步，结果所有操作都停留在「正在编译…」然后静默失败。
- 打开终端（
Ctrl+`），运行pdflatex --version或latexmk --version；有输出即说明环境变量已生效 - 若提示
command not found，说明 TeX 没装，或 PATH 没配对——Windows 用户常漏掉「将 MiKTeX bin 目录加入系统环境变量」这一步；macOS 用户用 Homebrew 装了texlive后，还需确认/usr/local/texlive/2023/bin/universal-darwin（年份依实际）已加进 shell 的PATH - 推荐初学者直接装完整版 TeX Live（而非精简版），避免编译时因缺宏包报错，比如
! LaTeX Error: File 'fontenc.sty' not found.
编写第一个 .tex 文件并触发编译
文件名、根文档标记、编译链三者必须匹配，否则 LaTeX Workshop 无法确定从哪开始构建。
- 新建文件，保存为
main.tex（建议用main或paper这类无空格、无中文的文件名） - 开头必须包含完整导言区，至少含
\documentclass{article}和\begin{document}...\end{document}；空文件或只有中文内容会编译失败 - 按
Ctrl+Alt+B（Windows/Linux）或Cmd+Alt+B（macOS）触发构建——不是Ctrl+S保存就自动编译，必须显式调用 - 首次编译可能耗时较长（尤其含 TikZ 或参考文献），耐心等右下角状态栏出现
Recipe terminated with exit code 0；若报错，点击左下角红色错误图标可跳转到具体行
PDF 预览与反向同步失效的常见原因
很多人以为 PDF 能弹出就万事大吉，但跳转不准、修改后不刷新、点击 PDF 无法定位源码，往往是配置细节被忽略。
- 预览 PDF 默认用 VSCode 内置查看器（
View in Web PDF），右键 PDF 页面可启用「SyncTeX from cursor」；但该功能依赖.synctex.gz文件生成，需确保编译命令含-synctex=1（latexmk默认开启，手动配置tools时易漏） - 如果改了
.tex文件但 PDF 不更新，先检查右下角是否显示「Auto Build: On」；若为 Off，点它切换，或手动按构建快捷键 - 使用
\include{}或\input{}分文件写作时，必须在主文件顶部添加注释行：% !TEX root = main.tex，否则插件会把子文件当独立文档处理，导致编译路径错乱 - PDF 查看器若设为外部程序（如 Skim/macOS 或 SumatraPDF/Windows），务必关闭其「文件监视」或「锁定 PDF」选项，否则 VSCode 无法覆盖写入新版本
真正卡住人的从来不是语法，而是 latexmk 找不到、synctex 没启用、root 注释漏写、PDF 查看器锁文件——这些点看似琐碎，却决定整个流程是否“感觉像在用 IDE”。
