初次配置 VSCode LaTeX SumatraPDF 这件事说难不难说简单也真能把人劝退。我第一次折腾的时候装完 TeX Live 发现命令行里敲不出 xelatex装完 VSCode 又不知道该配什么插件好不容易编译出 PDF点一下跳不回源码改个错别字得自己在几百行里翻。这套组合的价值就在于把这三个工具串成一条顺手的流水线VSCode 负责写和编LaTeX 发行版负责排版引擎SumatraPDF 负责预览并且支持正反向搜索。配置一次后面几年都能省事。这篇文章面向的是刚接触 LaTeX 排版、或者已经在用 Word 但被公式和参考文献折磨过的同学也适合那些装过 VSCode 但从来没认真配过插件的人。我会按我自己的实际配置流程走一遍每一步都说清楚为什么这么做、参数从哪来、错了怎么查。文中涉及的具体路径、命令行参数、settings.json 内容都可以直接抄改一下用户名就能用。1. 为什么是这套组合VSCode LaTeX SumatraPDF 的选型思路1.1 三个组件各自负责什么很多人一开始会把这三样东西混为一谈觉得装了 LaTeX 就能写论文了。实际上它们的分工非常清晰。TeX Live 或者 MiKTeX 是编译引擎它才是真正把 .tex 源码变成 PDF 的那个东西没有它VSCode 里写的东西就是一堆纯文本。VSCode 是编辑器它提供语法高亮、自动补全、代码片段、错误提示、编译快捷键让你的手不用离开键盘。SumatraPDF 是预览器它在连按编译的时候不会因为文件被占用而报无法写入的错而且它支持 SyncTeX 协议可以实现源码和 PDF 之间的双向跳转。三者的关系可以类比成做菜TeX Live 是灶台和锅VSCode 是切菜板和刀SumatraPDF 是摆盘用的盘子。缺了哪个都能看得见菜但整条流程就跑不通。1.2 为什么不用 TeXstudio 或者在线编辑器TeXstudio 本身是很成熟的 LaTeX 专用编辑器内置 PDF 预览、内置双向搜索开箱就能用这是它的优势。但如果你本来就在用 VSCode 写 Python、写 C、写 Markdown那再单独装一个 TeXstudio就意味着多一套快捷键、多一套主题、多一套插件生态切换成本其实不低。VSCode 配好 LaTeX Workshop 之后编辑体验和 TeXstudio 基本持平而且代码片段、Git 集成、多文件项目管理这些都直接复用你已有的习惯。在线编辑器的问题在于隐私和网络。论文、报告、内部文档这类内容很多人是不愿意放到公共服务器上的。而且一旦网络抽风你的写作节奏就断了。本地这套组合虽然初次配置麻烦一点但配完之后完全离线可用编译速度也取决于你自己的电脑不受别人影响。1.3 正向搜索与反向搜索这套组合真正的价值这是我要重点讲的东西也是很多人配完却没用起来的功能。正向搜索指的是光标停在 .tex 源码的某一行按一个快捷键PDF 预览窗口自动跳到对应的排版位置。反向搜索指的是在 PDF 里双击某段文字编辑器自动跳到生成这段文字的那一行源码。对于写长文档的人来说这两个功能是决定效率的关键。我改一个公式从 200 页的 PDF 里找它是哪一段靠肉眼翻可能要一分钟反向搜索双击一下就定位到了。同样看到 PDF 里某处排版奇怪正向搜索一秒回到源码位置。这套功能依赖 SyncTeX 这个机制。编译的时候需要加-synctex1参数生成一个 .synctex.gz 文件里面记录了源码行号和 PDF 坐标的对应关系。SumatraPDF 因为启动快、不锁文件、命令行参数支持得好成了 Windows 上配合 LaTeX 编辑器的常见选择。2. 安装前的准备环境规划与文件目录设计2.1 TeX 发行版选谁TeX Live 还是 MiKTeXWindows 上主流就两个选择。TeX Live是完整发行版一次性装完大约 5 到 8 GB包含几乎所有宏包装完之后基本不会再缺东西。MiKTeX是精简安装初始体积小用到哪个宏包就临时下载哪个。我的建议很直接如果你硬盘空间够、网络状况一般、或者需要交付给别人复现环境选 TeX Live。因为 MiKTeX 的按需下载在编译时会卡住你敲了编译命令它在那儿默默下载一个几十兆的宏包进度条不动你会以为程序挂了。TeX Live 一次装完后面就是纯粹的本地编译心态会好很多。如果硬盘实在紧张比如只有一块 128G 的系统盘那 MiKTeX 也能用但要在它的设置里把安装缺失宏包改为先询问避免它在后台悄悄下载。2.2 目录结构怎么规划我踩过的坑里路径问题占了相当大的比例。绝对不要在路径里带中文、空格和特殊符号。C:\Users\张三\我的论文\这种路径在某些宏包和某些命令行调用下会出现乱码或者找不到文件。同理D:\My Thesis\这种带空格的路径如果配置里忘记加引号命令行会被截断成两段。我现在的习惯是在非系统盘建一个纯英文、无空格的根目录比如D:\tex\ ├─ 2024-paper-a\ │ ├─ main.tex │ ├─ refs.bib │ ├─ figures\ │ └─ build\ (输出目录放编译产物) ├─ 2024-report\ └─ templates\ (放常用的论文模板)把编译产物单独放 build 目录是个好习惯。LaTeX 编译一次会产生 .aux、.log、.out、.toc、.synctex.gz 等一堆文件全部堆在源码目录里你的文件列表很快就会被淹掉。LaTeX Workshop 支持outDir配置可以把这些杂物统一扔到一个文件夹。2.3 版本与磁盘空间的实际考量TeX Live 每年发一个新版本版本号就是年份。新版本的好处是宏包更新、对新系统兼容性更好坏处是如果你之前配好的项目依赖某个旧宏包行为升级后可能报错。我的做法是装当前年份的版本然后在项目里用一段时间不升级等手里的活交付完再考虑换。磁盘方面完整安装 TeX Live 大概需要 8 GB 左右加上缓存和临时文件建议预留 15 GB。VSCode 本体加上插件大概 1 GBSumatraPDF 只有几兆。如果你打算用 Git 管理论文还会额外占用一些空间但纯文本的增量很小。3. 手把手安装三步走的具体操作3.1 安装 TeX Live到 TeX Live 官网下载 Windows 安装器。下载页通常会提供两种方式一种是网络安装器install-tl-windows.exe体积小但安装过程依赖网络另一种是完整 ISO 镜像体积大但安装过程完全离线。网络状况不好的话直接下 ISO挂载后运行 install-tl-windows.bat。安装过程中有几个选项要注意安装方案scheme选scheme-full。虽然体积大但省掉了后面缺宏包的麻烦。如果你确定只写简单文档scheme-basic也行但补装宏包的命令tlmgr install xxx会成为你的日常。安装路径默认是C:\texlive\2024建议保持默认。改到别的盘也可以但路径里不要有空格和中文。环境变量安装器会自动把C:\texlive\2024\bin\windows加入 PATH。如果不确定装完后在命令行敲xelatex --version验证。安装时间取决于磁盘速度机械硬盘可能要 40 分钟以上固态硬盘一般在 15 到 25 分钟。安装过程中不要点取消、不要关窗口中途断掉留下的半成品清理起来很麻烦。装完后做三个验证xelatex --version pdflatex --version tlmgr --version三条都有输出说明基础环境没问题。如果提示不是内部或外部命令去系统属性 → 高级 → 环境变量里检查 PATH把 TeX Live 的 bin 目录补上然后重开一个命令行窗口旧窗口不会刷新环境变量。提示如果你在中国大陆TeX Live 下载速度慢的话可以在安装器界面里把镜像源切换为国内高校的 CTAN 镜像速度会有明显改善。3.2 安装 VSCode 与中文界面VSCode 从官网下载 Windows 安装包安装时勾选添加到 PATH和将通过 Code 打开操作添加到资源管理器目录上下文菜单这两个选项对后面的命令行调用和右键打开文件夹很有用。装完后如果界面是英文按CtrlShiftX打开扩展面板搜索Chinese (Simplified) Language Pack安装后重启界面就变成中文了。这一步纯粹是为了降低阅读成本你要是习惯英文界面跳过也完全没问题。3.3 安装 SumatraPDF 并设为 PDF 阅读器SumatraPDF 官网提供安装版和便携版两种。便携版解压即用不写注册表适合放在 U 盘里带着走。安装版在系统里注册得更完整双击 PDF 时更好关联。安装路径我建议用默认的C:\Program Files\SumatraPDF\因为后面配置里要写完整路径默认路径不容易记错。装完之后做两步设置第一把 SumatraPDF 设为 .pdf 的默认打开方式这样双击编译产物不会被 Edge 或者别的阅读器抢走。第二打开 SumatraPDF 的菜单 → 设置 → 选项在下方找到反向搜索命令行Set inverse search command line这个输入框先放着等第 5 节配完 VSCode 再回来填。4. VSCode 侧的核心配置LaTeX Workshop 详解4.1 安装插件与理解它的默认行为在扩展面板搜索LaTeX Workshop作者是 James Yu装它。这个插件基本是 VSCode 里写 LaTeX 的事实标准。除此之外LaTeX Utilities可以作为补充提供一些格式化、字数统计之类的小功能不是必需。LaTeX Workshop 的默认行为需要提前知道否则你会困惑于为什么它老是自动编译。默认情况下latex-workshop.latex.autoBuild.run是onFileChange也就是你每改一个字符、保存一次它就触发一次编译。对于简单文档这很方便但对于多文件项目或者带参考文献的文档一次编译可能要十几秒你会被频繁打断。我个人的配置是把它改成onSave只在保存时编译。更激进的用法是设成never完全手动按CtrlAltB触发。4.2 settings.json 关键配置逐条解释按CtrlShiftP输入Open User Settings (JSON)打开用户设置文件。下面这份配置可以直接用路径部分改成你自己的{ latex-workshop.latex.outDir: %DIR%/build, latex-workshop.latex.autoBuild.run: onSave, latex-workshop.latex.autoClean.run: onBuilt, latex-workshop.latex.clean.subfolder.enabled: true, latex-workshop.latex.recipes: [ { name: xelatex x2, tools: [xelatex, xelatex] }, { name: xelatex - bibtex - xelatex x2, tools: [xelatex, bibtex, xelatex, xelatex] }, { name: latexmk (xelatex), tools: [latexmk_xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -output-directory%OUTDIR%, %DOC% ], env: {} }, { name: bibtex, command: bibtex, args: [%DOCFILE%], env: {} }, { name: latexmk_xelatex, command: latexmk, args: [ -xelatex, -synctex1, -interactionnonstopmode, -file-line-error, -outdir%OUTDIR%, %DOC% ], env: {} } ], latex-workshop.view.pdf.viewer: external, latex-workshop.view.pdf.external.viewer.command: C:/Program Files/SumatraPDF/SumatraPDF.exe, latex-workshop.view.pdf.external.viewer.args: [ -forward-search, %TEX%, %LINE%, %PDF% ], latex-workshop.view.pdf.external.synctex.command: C:/Program Files/SumatraPDF/SumatraPDF.exe, latex-workshop.view.pdf.external.synctex.args: [ -forward-search, %TEX%, %LINE%, %PDF% ] }逐条说清楚这些配置在干什么。outDir设成%DIR%/build意思是编译产物统一输出到源码所在目录下的 build 文件夹。%DIR%是 LaTeX Workshop 提供的变量代表当前 .tex 文件所在目录。这样你的源码目录里只会留下 .tex、.bib、图片这些人写的东西产物全在 build 里清爽很多。autoBuild.run设成onSave前面解释过避免每敲一个字就编译。autoClean.run设成onBuilt意思是每次成功编译后自动清理中间文件。这里要注意它清理的是 build 目录里的 .aux、.log 这类文件但会保留 PDF 和 .synctex.gz这两个是预览和双向搜索需要的。如果你在调试参考文献建议临时改成never因为清掉 .aux 和 .bbl 之后引用编号会变成问号。tools里那几个-开头的参数作用分别是参数作用不写的后果-synctex1生成 SyncTeX 映射文件双向搜索完全失效-interactionnonstopmode遇到错误不停下来等输入编译卡死必须手动杀进程-file-line-error报错信息带上文件名和行号只能看到一大堆无用的上下文-output-directory指定输出目录产物散落在源码目录-interactionnonstopmode这条特别重要。LaTeX 默认是遇到错误停下来等你敲回车继续而编辑器调用它的时候没有交互终端进程就僵在那儿了。我第一次遇到的时候以为电脑死机了。4.3 编译链为什么要跑多遍xelatex x2这个 recipe 跑两遍不是凑数。LaTeX 的交叉引用、目录、页码这些信息是靠\label和\ref写入 .aux 文件、下一遍编译再读回来实现的。第一遍收集信息第二遍才能把引用正确渲染出来。如果你发现 PDF 里引用编号是问号、目录页码是 0基本就是编译遍数不够。带参考文献的情况更复杂顺序是xelatex—— 生成 .aux里面有引用标记bibtex—— 读 .aux 和 .bib生成 .bblxelatex—— 把 .bbl 里的文献列表排进去xelatex—— 重新计算引用编号和页码所以xelatex - bibtex - xelatex x2这个 recipe 是四步。少一步都可能出问题。另一种更省心的方案是用latexmk。它会自动分析依赖关系判断需要跑几遍、要不要跑 bibtex然后一次性搞定。缺点是它会多看几个文件、多花一点时间但心智负担小很多。我的建议是刚开始用显式的 recipe搞清楚每步在干什么熟了之后切 latexmk。还有一个隐藏参数要提如果你用 PDFLaTeX 而不是 XeLaTeX中文会乱码。XeLaTeX 对 Unicode 和中文字体的支持是三个引擎里最省事的所以中文文档统一用 xelatex并在导言区写\documentclass[12pt, a4paper]{ctexart}ctexart是 ctex 宏包提供的文档类会自动处理中文字体、行距、标点。用\documentclass{article}再单独\usepackage{ctex}也可以但字体配置要自己多写几行。5. SumatraPDF 与双向搜索的打通5.1 反向搜索从 PDF 跳回源码VSCode 那一侧的配置只是告诉插件怎么打开 SumatraPDF真正让反向搜索生效的是 SumatraPDF 里的命令行设置。回到 SumatraPDF菜单 → 设置 → 选项在反向搜索命令行里填入C:\Program Files\Microsoft VS Code\Code.exe -g %f:%l如果你的 VSCode 装在用户目录下路径要改成类似C:\Users\你的用户名\AppData\Local\Programs\Microsoft VS Code\Code.exe -g %f:%l%f是文件完整路径%l是行号这两个是 SumatraPDF 的占位符。-g是 VSCode 的跳转参数格式是文件:行号。--reuse-window这个参数可选加上它会在当前窗口打开不加则可能新建窗口。配置完之后必须重新编译一次因为 .synctex.gz 是编译时生成的。然后打开 PDF双击任意一段文字VSCode 应该跳到对应的源码行。如果双击没反应按这个顺序排查PDF 是不是最新编译的确认 build 目录里有 .synctex.gz源码路径里是不是有中文或空格SumatraPDF 里那段命令的引号是不是英文引号。这三条命中率最高。5.2 正向搜索从源码跳到 PDF正向搜索在 VSCode 里触发默认快捷键是CtrlAltJ也可以在命令面板里搜LaTeX Workshop: SyncTeX from cursor。这里有一个绕不开的坑SumatraPDF 可能已经在运行但新的调用会被转发给已有进程导致跳转失效。解决办法是在latex-workshop.view.pdf.external.viewer.args里只保留-forward-search %TEX% %LINE% %PDF%这三个参数不要加别的干扰项。另外确保你在 settings.json 里用的是绝对路径并且路径中使用的是正斜杠/或者双反斜杠\\单个反斜杠在 JSON 里是转义字符会解析失败。5.3 实测验证方法配完之后我一般这样验证在 main.tex 的正文里随便找一句独特的话比如下面这个结论非常重要。编译一次等 PDF 自动弹出或者手动用快捷键打开。光标停在那句话所在行按CtrlAltJ。PDF 应该滚到那句话的位置并高亮。回到 PDF双击那句话所在的区域VSCode 应该跳到那句话的行。两步都通说明整套链路是活的。我建议每换一台新机器都跑一遍这个验证别等到赶稿子的时候才发现跳转不能用。注意正向搜索首次使用时SumatraPDF 可能弹出安全提示或者窗口没有前置。如果 PDF 滚动了但窗口没到前面手动切一下即可功能本身是正常的。6. 常见问题与排查实录6.1 编译报错速查表LaTeX 的报错信息经常让人一头雾水因为它一层层地套。我的经验是只看第一个!开头的错误后面的往往是它的连锁反应。下面这张表是我这几年遇到频率最高的几类报错关键词常见原因处理方式File xxx.sty not found宏包没装执行tlmgr install 宏包名或换用 TeX Live 完整版Undefined control sequence命令名拼错或宏包没引入检查\usepackage确认命令拼写Missing $ inserted数学符号写在了数学环境外用$...$或\[...\]包起来! LaTeX Error: File xxx.eps not found图片路径或格式不对用 XeLaTeX 时优先用 PDF 或 PNG 图片Emergency stop前面有致命错误往上翻找到第一个真正的错误Font ... not found中文字体配置错误用 ctex 宏包别手动设字体Citation xxx undefined编译遍数不够或 .bib 未生效换成带 bibtex 的四步 recipePackage hyperref Warning一般只是警告可以忽略不影响输出顺便说一句-file-line-error参数打开之后报错信息会变成main.tex:42: Undefined control sequence这种格式直接告诉你哪一行省掉大量找行号的时间。6.2 中文与字体相关的坑中文文档最容易出的问题是字体。常见表现为编译成功但 PDF 里某些字是方框或者空白。原因通常是系统里缺某个字体或者字体名写错了。用ctexart文档类时它会自动调用系统里的中文字体一般不需要手动配。如果你想指定字体写法是\setCJKmainfont{字体名}字体名必须和系统里显示的完全一致差一个字都不行。SimSun、SimHei、Microsoft YaHei这几个是 Windows 上比较通用的选择。另一个坑是.tex文件的编码。XeLaTeX 要求源码是 UTF-8 编码VSCode 默认就是 UTF-8一般不用管。但如果你从别人那里拿到一个 GBK 编码的老文件打开后中文会变成乱码这时候要在 VSCode 右下角点编码切换选通过编码重新打开选 GBK再通过编码保存选 UTF-8。6.3 编辑器与插件层面的杂项问题自动编译太频繁导致卡顿。前面提过把autoBuild.run改成onSave。如果你的文档特别大几百页建议直接设成never用快捷键手动编译。build 目录里的文件被反复重建Git 里出现大量变更。在项目根目录加一个.gitignore把build/加进去。这样版本库里只保留源码干净得多。改了 settings.json 但没生效。VSCode 的配置文件是即时生效的但 LaTeX Workshop 的部分配置需要重新加载窗口按CtrlShiftP搜Reload Window执行一次就好。C 盘空间被 TeX 缓存吃掉。TeX Live 在运行时会往用户目录写字体缓存路径一般在C:\Users\用户名\AppData\Local\MiKTeX或者 TeX Live 对应的缓存目录。如果空间紧张可以用tlmgr清理或者直接把整个 TeX Live 装到非系统盘。同时装了 MiKTeX 和 TeX Live。这是个经典问题两个发行版的 PATH 会打架命令行里敲xelatex到底调的是哪个不确定。解决方式是只保留一个在 PATH 里另一个从环境变量里移除。要么就干脆只装一个。从 Word 复制过来的公式粘贴到 LaTeX 里显示异常。Word 的公式是 OMML 格式不是 LaTeX 源码直接粘贴当然渲染不出来。正确的做法是把 Word 公式转成 LaTeX 代码再粘或者干脆在 LaTeX 里重写一遍。反过来把 LaTeX 公式放进 Word 里也需要用支持 LaTeX 语法的输入方式不能直接贴纯文本。6.4 一份可以直接抄的排错流程我把排错顺序整理成一个固定动作遇到问题就按这个走看 build 目录里的 .log 文件搜第一个!找到出错文件和行号。单独在命令行里编译一次cd到源码目录敲xelatex -interactionnonstopmode -file-line-error main.tex看完整报错。注释掉最近改动的部分二分法定位。这个是笨办法但命中率百分之百。确认宏包是否存在tlmgr show 宏包名有输出说明装了。确认图片路径和格式XeLaTeX 对 EPS 支持不好尽量用 PDF、PNG、JPG。确认编译引擎中文文档必须 xelatex 或者 lualatex不能用 pdflatex。还有一个技巧在 .tex 文件的第一行写魔法注释% !TeX program xelatexLaTeX Workshop 会读这行来决定用哪个引擎。多文件项目里这个注释能避免配置里写的是 xelatex但某个文件被别的工具用 pdflatex 编了这种混乱。这套配置我从第一次折腾到现在前后改过七八版 settings.json。最开始是照抄别人的后来发现很多参数自己根本没搞懂为什么这么写出问题就只能瞎试。真正搞明白-synctex1、-interactionnonstopmode、编译遍数这些概念之后再遇到报错就不慌了。我个人在实际操作中的体会是先把命令行这条链路跑通再去配编辑器。先在命令行里手敲xelatex main.tex能出 PDF说明引擎没问题再配 VSCode 的 recipe说明编辑器调用没问题最后配 SumatraPDF 的反向搜索说明预览器和编辑器的通信没问题。这三层分开验证出问题的时候你能立刻知道是哪一层断了而不是对着一堆配置猜。最后分享一个小习惯每次开新项目我会把一份配好的 settings.json 和.gitignore复制过去再写一个几百字的 README 记下这个项目用的引擎和特殊宏包。半年后回头看这几行字能省掉半小时的回忆时间。