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/2025/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”。