VS Code 搭建 LaTeX 编译环境：XeLaTeX 与 latexmk 配置详解

写论文的时候第一次在 VS Code 里打开一个.tex文件光标停在\documentclass{article}那一行却完全不知道这一份文档到底能不能编译出 PDF——如果你也跟我当初一样被“LaTeX 编译环境”这几个字绕晕过那这篇内容就是给你准备的。我帮人配过几十次环境也亲眼见过有人在配置这一步卡了整整一个下午最后才发现只是漏装了一个发行版。其实整件事没那么玄你只需要搞清楚两件事电脑上有没有 LaTeX 引擎编辑器能不能把指令正确传给引擎。前者靠 TeX 发行版解决后者靠 VS Code 加扩展解决。这篇文章会从设计思路讲起把发行版选择、扩展安装、settings.json逐项拆解、最小示例运行、常见问题排查一次性讲透适合第一次接触 LaTeX 的学生也适合想从其他编辑器迁移过来的人。1. 为什么是 VS Code整套方案的设计思路1.1 常见编辑器对比VS Code 赢在哪市面上面向 LaTeX 的编辑器不算少老牌的 TeXstudio、WinEdt以及现在很多人直接用的 Overleaf 在线版。TeXstudio 对 LaTeX 的补全做得挺全但界面风格偏“复古”而且只服务于 LaTeX 单一场景Overleaf 胜在免配置、云端协作方便但一旦要求本地编译、需要高性能计算或者想和 Git 工作流打通它就有点力不从心。VS Code 的核心优势在于它不是一个“LaTeX 编辑器”而是一个通用编辑器。你可以在同一个窗口里写.tex、写 Python、画流程图、提交 Git。搭配 LaTeX Workshop 扩展后它的 LaTeX 支持并不输给 TeXstudio甚至因为高度可配置用起来更顺手。对长期需要写论文、做笔记、写博客的人来说这种“一个环境通吃”的价值非常大。1.2 两层结构TeX 发行版和编辑器扩展很多人卡在配置环节根源在于混淆了两个概念。VS Code 本身不负责“排版”它只是一个文本编辑器和指令调度器。真正把.tex文件翻译成 PDF 的是安装在你系统里的 TeX 发行版。所以整套环境从结构上看是两层底层TeX 发行版提供xelatex、pdfLaTeX、latexmk等可执行程序以及大量宏包。上层VS Code LaTeX Workshop负责编辑、调用编译命令、解析日志、预览 PDF、正反搜索。这个边界一旦清晰你遇到“无法编译”“找不到命令”这类问题时就能很快定位是底层缺失还是上层配置错误而不是瞎改一通配置。后面所有操作都围绕这两层展开。1.3 先看懂编译链路pdfLaTeX、XeLaTeX 和 latexmk写 LaTeX 文档的人经常把“编译”当成一个整体动作但真正编译时其实涉及多个程序。理解这条链路有助于你配置时做到心中有数。最基本的图片是main.tex文件被某种引擎处理生成 PDF。但一个文档里往往有交叉引用、参考文献、索引这些需要多轮编译才能稳定解析。比如引用关系第一次编译未必完整需要跑第二遍如果用了 BibTeX顺序通常要变成编译 - bibtex - 编译 - 编译。三种常见引擎需要分清pdfLaTeX最传统的方式直接把.tex编译成 PDF但对中文字体的支持比较麻烦。XeLaTeX支持 Unicode 和系统字体是目前中文文档最常用的引擎。配合ctex或xeCJK宏包可以很方便地使用系统中文字体。LuaLaTeX类似 XeLaTeX而且内置了 Lua 脚本能力部分宏包生态更现代但普及度稍逊。为了不让每次编译都手动跑好几遍业界习惯使用latexmk这个“导演型”工具它会根据文档情况自动决定执行几次编译、要不要调用 BibTeX你只需要告诉它“用哪个引擎”。正因为这样LaTeX Workshop 默认配置里通常都会把latexmk包在最外层而不是直接调用xelatex。这一点理解到位你配置时就能少踩一半坑。2. 环境准备装好 TeX 发行版验证一切的前提2.1 三大主流发行版怎么选TeX 发行版是底层你必须先装它。常见的三个名字是 TeX Live、MiKTeX 和 MacTeX。TeX Live跨平台最完整也最权威Windows/Linux 上首选。安装完整版之后几乎不用再手动补包因为常用宏包都包含在内。MiKTeXWindows 上的历史选项特色是“缺什么装什么”编译时自动下载缺失宏包。听起来方便但在离线环境或网络不稳时会很尴尬而且自动安装过程偶尔会打断编译。MacTeX本质是 macOS 上的 TeX Live 预打包版macOS 用户直接选它。如果你不确定选哪个我建议Windows 和 Linux 用户直接上 TeX LivemacOS 用户用 MacTeX。这组合已经经过了大量文档和社区验证没有必要在发行版选择上炫技。2.2 安装过程的实操建议TeX Live 的完整安装包体积不小以 Windows 为例安装时可以选择安装全部 scheme默认全套也可以选基本版加后续tlmgr按需安装宏包。给新手的建议很直接如果你是第一次装、且网络没问题直接装完整版。虽然体积大但能省去后来为了一个宏包反复折腾的烦恼。安装过程中有几个细节值得注意安装路径最好保持英文避免某些工具对中文路径解析异常。安装完成后打开新的终端旧终端不会自动拿到新的 PATH执行xelatex --version如果看到版本信息说明发行版已经正常工作。如果提示“不是内部或外部命令”需要手动把 TeX Live 的bin目录加进系统环境变量或者重装时记得勾选“添加到 PATH”。执行验证这一步极其重要因为它能帮你区分“发行版没装好”和“VS Code 配置错了”。我见过很多人配置出错折腾半天扩展和 JSON最后才发现是终端里根本找不到xelatex。2.3 中文字体、编码和引擎的关联如果你主要写中文论文引擎选择基本锁定 XeLaTeX。原因是它原生支持 UTF-8 编码和系统字体调用配合ctex宏包后中文支持非常自然。一个典型的中文文档开头通常是\documentclass[UTF8]{ctexart} \begin{document} 你好LaTeX。 \end{document}这个文件只能用xelatex编译或者用latexmk并指定-xelatex参数。如果你误用pdfLaTeX大概率会得到乱码或一堆字体错误。记住这个映射关系“中文场景默认 XeLaTeX纯英文场景用什么都行但推荐 XeLaTeX”。这样你的配置思路就统一了。3. 配置 VS Code扩展与 settings.json 的核心参数3.1 安装 LaTeX Workshop 扩展在 VS Code 的扩展面板里搜索LaTeX Workshop认准那个 LaTeX 图标安装量最高那个就是。装完后重启窗口扩展会自动接管.tex文件的编辑体验包括语法高亮、大纲结构、代码补全、编译按钮、PDF 预览。但注意扩展默认的编译行为不一定符合你的中文场景。很多人装完扩展就以为配置完成结果一编译报错这就是因为默认配方和你的需求不匹配。所以接下来必须进入settings.json做定制。在 VS Code 里按CtrlShiftP输入open user settings选择“打开用户设置 (JSON)”就能看到自己的配置文件。下面这些参数是核心。3.2 settings.json 核心参数tools 与 recipesLaTeX Workshop 的配置模型就两个关键词tools和recipes。tools定义“可以执行哪些命令”recipes定义“按什么顺序执行哪些命令”。理解这个模型你就能自由定制编译流程。先看一个适合中文场景的基础配置{ latex-workshop.latex.tools: [ { name: latexmk, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, -xelatex, %DOC% ] } ], latex-workshop.latex.recipes: [ { name: latexmk-xelatex, tools: [latexmk] } ] }这段配置我建议第一次配置的人直接抄过去原因如下-synctex1开启正反搜索这个后面会讲。-interactionnonstopmode遇到错误时不要停下来等用户输入否则 VS Code 的编译过程会挂起。-file-line-error让错误日志带上行号方便定位。-pdf -xelatex指定用 XeLaTeX 引擎并输出 PDF。%DOC%是 LaTeX Workshop 提供的变量表示当前主文件的完整路径扩展会自动替换。可能有人会好奇tools里只定义了一种工具recipes里也只放了一个“配方”是不是太简单了对但这正是“显式声明优于隐式依赖”的做法。如果你不自己声明LaTeX Workshop 也有默认的pdflatex - bibtex - pdflatex类配方但那个在中文场景下并不合适。你自己写清楚后面出问题也容易排查。另一个重要参数是%DOC%与%TEX%的差异%DOC%是指当前文档的完整路径%TEX%是指“主文件”的路径。当你想把自己写的文档作为主入口时需要设置latex-workshop.latex.root.files或者借助%TEX%来追踪但刚入门不需要关注默认即可。3.3 辅助参数自动构建、清理与 PDF 预览基础工具配好后还有几个参数直接影响日常体验。第一个是自动构建时机{ latex-workshop.latex.autoBuild.run: onSave }改成onSave意思是每次保存.tex文件都会自动触发编译这是我认为最省心的模式。你也可以设成never然后手动按键构建。但新手阶段建议onSave因为即时能看到错误反馈学习体验好很多。第二个是清理辅助文件。LaTeX 编译会生成大量.aux、.log、.out、.toc文件这些是中间产物不必每次都手动删。你可以配置{ latex-workshop.latex.clean.fileTypes: [ *.aux, *.log, *.out, *.toc, *.fls, *.fdb_latexmk, *.synctex.gz, *.bbl, *.blg ], latex-workshop.latex.clean.subfolder.enabled: true }清理命令会在 LaTeX Workshop 的界面按钮里触发避免你手动开终端删文件。不过要注意清理时机需谨慎别在编译过程中去点清理否则可能出现文件被占用的奇怪问题。第三个是 PDF 预览方式。我推荐用的是内部查看器{ latex-workshop.view.pdf.viewer: tab }这个模式会在 VS Code 右侧标签页显示 PDF而不是跳转外部浏览器阅读体验最好。配合latex-workshop.view.pdf.ref.viewer的默认值可以保持源代码和 PDF 滚动同步。3.4 正向、反向搜索把 PDF 和源码绑在一起用 LaTeX 写长文档最爽的操作就是“从 PDF 某一行跳回源码对应位置”或者“从源码某一行跳回 PDF 对应位置”。这个功能依赖 SyncTeX 支持而前面配置里的-synctex1已经为它铺好了路。在 VS Code 里默认的实现方式是这样正向搜索源码到 PDF在.tex文件里按住CtrlmacOS 上是Cmd并点击某一行右侧 PDF 会跳转到对应位置并高亮显示。反向搜索PDF 到源码在 PDF 查看器里按住CtrlmacOS 上是Cmd并点击某个位置源码会跳到对应行。如果你发现点击没有反应先检查-synctex1是否在编译参数里。另外有的用户会额外配置自定义快捷键但新手阶段不需要动这些。默认行为已经足够好用。4. 实操流程从新建文件到生成第一份 PDF4.1 最小可编译示例我不建议一上来就写完整论文而是先跑通一个最小示例。新建一个文件夹demo-latex用 VS Code 打开后创建一个main.tex\documentclass[UTF8]{ctexart} \usepackage{lipsum} \title{我的第一份 LaTeX 文档} \author{匿名用户} \date{\today} \begin{document} \maketitle \section{引言} 这是一个中文 LaTeX 最小示例。如果你能看到这段文字以及之后的 PDF 文件说明你的 VS Code 编译环境已经跑通了。 \lipsum[1] \end{document}这个文件虽然短但包含了几层作用ctexart提供中文排版支持lipsum包生成一段样板文字\maketitle和\section验证标题和章节结构。如果它能编译通过说明大多数基础情况都没问题。4.2 触发编译手动构建与自动构建写完文件后保存一次。如果你按照前面的配置设置了onSave扩展应该已经开始编译了。右下角状态栏会显示√ 编译完成或× 编译失败。如果你没有开启onSave则需要手动触发。LaTeX Workshop 在左侧侧边栏提供了一组按钮包括“Build LaTeX project”“View LaTeX PDF”“Clean up auxiliary files”等。这些按钮位置非常直观用一两次就会习惯。键盘党可以在命令面板中搜索latex-workshop.build来绑定快捷键但这不是必须的。编译过程中改动文件容易引发不确定性问题。我一般会养成的习惯是保存后停一两秒再继续编辑等构建结果出来再动手。latexmk跑的速度通常很快但这段时间足够让日志系统稳定。4.3 预览和正反搜体验编译成功后点击侧边栏“View LaTeX PDF”按钮PDF 会出现在右侧标签页。这时你可以验证中文字体是否正常显示标题、章节是否渲染正确源码和 PDF 是否同步滚动。我个人测试标准很简单把这个示例文档跑通后再复制一份正式论文进来编译一次。如果两者都成功你的环境基本就稳定了不用反复折腾配置。5. 常见问题与排查技巧实录5.1 高频问题速查表下面这些是我在实际使用和帮别人排查时遇到最多的几类问题直接整理成表格问题表现可能原因解决方案编译提示xelatex: not foundTeX 发行版未安装或 PATH 未配置终端里执行xelatex --version确认有输出没有则重新安装发行版或手动添加 PATH编译报错! LaTeX Error: File xxx.sty not found缺少对应宏包使用完整版 TeX Live 安装一般不会有此问题否则用tlmgr install xxx按需安装中文变成乱码或黑框使用了pdfLaTeX编译中文文档确保编译配方指定-xelatex并让文档加载ctex宏包PDF 没有自动刷新预览视图未正确绑定构建结果点击 PDF 查看器里的“重新打开”按钮检查latex-workshop.view.pdf.viewer是否为tab保存后不自动编译未设置onSave或扩展未激活将latex-workshop.latex.autoBuild.run设为onSave确认已安装 LaTeX Workshop 并重载窗口报错Recipe unavailablerecipes中引用的tools名称拼写不一致检查settings.json中tools[i].name与recipes[0].tools的名称完全一致编译日志全是英文句子但看不懂缺少-file-line-error参数错误定位困难在latexmk参数中加上-file-line-error然后从日志中的.tex:数字定位5.2 从日志入手错误信息怎么看遇到编译失败时大多数人会直接看 PDF 有没有生成然后茫然不知所措。正确做法是先打开输出面板菜单栏“终端” - “运行生成任务”不对LaTeX Workshop 的输出一般在“查看” - “输出”里然后在输出窗口右上角下拉框选择LaTeX Workshop。日志里最有价值的行是带有error、Error或!的行它们通常会告诉你具体的文件名和行号。比如上面配置了-file-line-error后日志会出现类似./main.tex:12: Undefined control sequence.的内容直接跳转到源码对应行修改即可。如果没有行号信息你也能根据宏包名和错误描述去搜索。排查逻辑简单来说就是先把错误文本复制到搜索框里看常见解法再对照表格排查环境层原因。大部分问题不会同时由两层引起所以一层一层排查很快就能定位。5.3 配置了一份 settings.json 后还应该注意什么最后分享几个我踩过的坑和现在的固定习惯。路径中不要带特殊字符。虽然现代工具经常能处理空格和中文路径但 LaTeX 生态里仍有一些工具对特殊字符敏感。我把所有 LaTeX 项目都放在英文路径下尤其避免中文和中文空格组合。这不是必须的但能让你少很多莫名其妙的烦恼。不要在编译过程中重启 VS Code 或切换 Git 分支。用latexmk时编译状态会写在缓存文件里中途强制中断容易导致下次构建时状态错乱。真遇到这种情况就点击 LaTeX Workshop 侧边栏里的“Clean up auxiliary files”清掉缓存再重新构建。自动构建和手动清理要拉开距离。我习惯让自动构建在onSave模式下工作但清理辅助文件只用“手动触发”。这样可以避免每次保存后PDF 因为清理动作出现短暂闪断。我现在最终的固定配置就是本文 3.2 节里那份settings.json加两行autoBuild和viewer参数。每次换一台机器我会先复制这份配置再跑一遍最小示例。这一步看起来简单实际上替我挡掉了很多“新机器配不出来”的时间消耗。如果你刚接触这套环境不用急着追求花哨的快捷键或复杂配方先把最小示例跑通再一点一点往配置里加东西。跑通这个流程之后LaTeX 就不再是“配置地狱”而是你写作时真正能托付的排版系统了。