企业官网建设流程全解析

聊一个几乎每个 LaTeX 用户在 VSCode 里都会撞上的场景：装好 LaTeX Workshop，从网上复制了一段 settings.json，满怀期待地打开 .tex 文件，按下编译，输出面板立刻滚出一屏红色日志，"Recipe terminated with fatal error"，然后就没有然后了。最让人崩溃的是，网上的配置看起来全都一样，抄到别人电脑上就正常，到了自己这里就是报错；同一份配置换台电脑偶尔又能跑起来，折腾到最后甚至怀疑 VSCode 是不是需要重装。

这篇文章想做的事情很直接：把 VSCode 下 LaTeX 编译这条链路从头到尾理顺——点下编译按钮之后到底发生了什么，settings.json 里每个配置项之间是怎么配合的，以及那些高频报错应该走什么样的排查路径。文末会给出我用了很久的一份完整配置，Windows、macOS、Linux 三套系统都在跑，属于配一次就能一直用的那种。你完全可以先抄走，跑通再回头看我解释的原理；如果你的目标只是“能编译”，从后面配置部分开始看也没问题，但想彻底告别对着报错瞎试的日子，我建议从头读一遍。

1. 编译引擎装不对，后面全白搭：TeX Live 的选择与 PATH 问题

很多人以为装好 VSCode 和插件就完事了，其实 VSCode 里跑 LaTeX 并不是“插件自带了编译器”。LaTeX Workshop 只是个前端，真正干活的是 TeX 发行版。这个逻辑如果没搞清楚，后面所有报错都会变得莫名其妙——你改再多的 settings.json，底层没有可执行的编译命令，一切都是白搭。

1.1 TeX Live 还是 MiKTeX

主流的 TeX 发行版就两个：TeX Live 和 MiKTeX。我的建议是，除非你有特殊原因，否则直接装 TeX Live，而且是完整版。

TeX Live 的优势在于跨平台一致性。Windows 上装的是它，macOS 上的 MacTeX 底层也是它，Linux 上 TUG 官方安装器装的还是它。这意味着你在三个系统里写 LaTeX，编译行为、宏包版本、报错信息几乎一样，不会出现“Windows 模板拿到 macOS 上就崩”的情况。MiKTeX 的看家本领是按需安装宏包，初始安装体积很小，Windows 下体验也更贴近普通软件，但问题恰恰出在“按需”两个字上——写论文写到一半缺个.sty文件，它弹一个窗口开始联网下载，网络一慢，整个进度就卡在那里。

全量安装 TeX Live 大概会占 7 到 8 GB 磁盘空间，对今天的主流硬盘来说压力不大，换来的是几乎所有宏包开箱即用。写毕业论文、期刊投稿、做简历、写技术文档，绝大多数场景根本不需要你手动装包。所以第一课就一句话：不要在这个环节省时间，装全量 TeX Live。

1.2 安装时最容易埋下的几个雷

安装 TeX Live 本身不难，难点在于装完之后环境里留了几个“暗雷”，我一个个说。

Windows 上，安装器会问你是装到用户目录还是系统目录。选用户目录时，可执行文件会出现在C:\Users\你的用户名\AppData\Local\Programs\texlive\2024\bin\windows这类路径下；选系统目录时则常见于C:\texlive\2024\bin\windows。不管选哪个，安装完第一步必须是重开终端。因为 PATH 环境变量在安装过程中被改了，但已经打开的终端不会自动加载新值。很多人的报错“spawn xelatex ENOENT”，问了一圈发现就是装完后没重开终端，VSCode 里继承的还是一个旧环境变量快照。

macOS 上装 MacTeX 也有类似的坑。它的可执行文件默认在/usr/local/texlive/2024/bin/universal-darwin下，安装器会试图把这个目录加进 shell 配置。但如果你平时从 Dock 图标启动 VSCode，它可能不会加载你.zshrc里写的 PATH。解决办法很简单：从终端执行code命令启动 VSCode，或者把 TeX Live 的 bin 目录写进系统的/etc/paths.d/里。实在不会弄，就在 VSCode 的设置里搜索terminal.integrated.env，手动指定 PATH。

Linux 用户最容易掉进的坑是用发行版自带包管理器装 TeX Live，比如apt install texlive-full。不是不能用，但很多发行版仓库里的 TeX Live 版本偏旧，宏包拆分方式也和官方不一致，容易出现模板要ctex宏包，你装了texlive-lang-chinese还是缺依赖的情况。我建议直接到 TUG 官网下载install-tl脚本安装，版本新，组件全，后面少很多麻烦。

1.3 装好后先验证这几条命令

配置任何东西之前，先在终端敲三轮命令，确认底层工具真的可用：

xelatex --version latexmk -v tlmgr --version

三条命令分别验证三件事：xelatex 编译器是否存在、latexmk 调度工具是否可用、TeX Live 的包管理器是否正常。如果xelatex --version能打印出版本信息，说明发行版本体没毛病；latexmk -v很重要，因为后面的配置里我会把它作为默认编译工具；tlmgr是以后手动装宏包的救命工具。

再进一步，用where xelatex（Windows）或which xelatex（macOS/Linux）看看可执行文件路径。理想情况下，xelatex 和 latexmk 应该指向同一个 TeX Live 目录。如果两个命令来自不同安装路径，说明你的环境变量里混入了旧版本 TeX 的残留，后续编译会出现各种诡异行为，真遇到了就把旧版本卸载干净，再重新配 PATH。

还有一个 Windows 专属的坑：不要用“管理员身份”运行 VSCode。管理员权限会触发 UAC 下的环境变量差异，导致 VSCode 里看到的 PATH 和普通终端里不一样。同一个项目，普通终端编译得好好的，VSCode 里一按就报找不到命令，八成是这个原因。这个坑我帮人排查过不止一次，每次都是查到最后才想起来问一句“你是不是用了管理员模式”。

2. LaTeX Workshop 配置拆解：一份能直接抄的 settings.json

环境准备好之后，真正花时间的其实是 VSCode 插件的配置。LaTeX Workshop 确实是目前最主流的 LaTeX 插件，功能很强，但它的配置项也足够让人眼花缭乱。很多教程贴出来的 settings.json 都是别人项目里的完整配置，字段又长又多，你复制过来根本不知道哪些是必需品，哪些只是为了满足原作者的特殊需求，最后一出错就抓瞎。

2.1 编译流程的真相：recipe 怎么调用 tool

在贴配置之前，我必须先把 LaTeX Workshop 的编译机制讲清楚，否则你以后还是不会排查问题。

LaTeX Workshop 把编译过程抽象成了两层：recipes和tools。tools定义的是“单条可执行命令”，比如“用 xelatex 编译一遍”是 tool，“用 bibtex 处理参考文献”是另一个 tool。recipes定义的是“一整条处理流程”，比如“先用 xelatex 编译，再跑 bibtex，最后再跑两遍 xelatex”。一个 recipe 会按顺序调用多个 tool。

很多人配置出问题，就是因为 recipe 里写了"xelatex"，但 tools 数组里根本没有定义 name 为xelatex的 tool，或者定义的名字大小写不一致。插件执行 recipe 时在 tools 里找不到对应项，直接抛错。这就好比你给厨师一张写有“青椒土豆丝”的菜单，但后厨压根没有这道菜的做法卡，最后只能给你端上一句“Recipe terminated with fatal error”。

排查的时候，在 VSCode 命令面板里输入LaTeX Workshop: Build with recipe，会列出所有 recipe，你可以一个个试，看到底是哪一步挂掉的。这个操作基本是解决问题的起点。

2.2 我日常在用的完整配置

下面这份配置是目前我在用的精简版本，没有多余的修饰项，Windows、macOS、Linux 通用。直接复制到 settings.json 里，重启窗口即可：

{ "latex-workshop.latex.tools": [ { "name": "latexmk", "command": "latexmk", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-xelatex", "-outdir=%OUTDIR%", "%DOC%" ], "env": {} }, { "name": "xelatex", "command": "xelatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "%DOC%" ], "env": {} }, { "name": "bibtex", "command": "bibtex", "args": [ "%DOCFILE%" ], "env": {} } ], "latex-workshop.latex.recipes": [ { "name": "latexmk (xelatex)", "tools": [ "latexmk" ] }, { "name": "xelatex -> bibtex -> xelatex * 2", "tools": [ "xelatex", "bibtex", "xelatex", "xelatex" ] }, { "name": "xelatex", "tools": [ "xelatex" ] } ], "latex-workshop.latex.autoBuild.run": "never", "latex-workshop.latex.autoBuild.interval": 1000, "latex-workshop.view.pdf.viewer": "tab", "latex-workshop.synctex.afterBuild.enabled": true, "latex-workshop.latex.clean.fileTypes": [ "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.fls", "*.log", "*.fdb_latexmk", "*.synctex.gz", "*.nav", "*.snm", "*.vrb" ], "latex-workshop.latex.clean.subfolder.enabled": true, "latex-workshop.latex.rootFile.doNotPrompt": false }

2.3 关键配置项逐个解释

tools里的每一项，核心是name、command、args三个字段。name是给 recipe 引用的 ID，可以随便起；command是真正在终端里执行的可执行程序名；args是命令行参数。里面出现的%DOC%是插件提供的魔法变量，代表当前根 TeX 文件的完整路径，%DOCFILE%是不带扩展名的文件名，%OUTDIR%是输出目录。我在 xelatex 参数里加了-synctex=1、-interaction=nonstopmode、-file-line-error三个常用项：-synctex=1生成正反搜索需要的映射文件，-interaction=nonstopmode遇到错误不暂停、一口气把编译跑完，-file-line-error让报错信息带文件名和行号，方便在 VSCode 里点击跳转。

recipes里我把latexmk (xelatex)放在第一位，这也是插件的默认选择；第二位放手动编译流程，是为了兼容那些必须严格控制编译顺序的老模板；第三位单独的 xelatex 适合临时用一下。tools数组里的名字必须能和recipes里的引用对得上，否则就会出现上一节说的错误。

autoBuild.run我设置成never，目的是不让插件每次保存都自动编译。虽然自动编译看起来很爽，但文档一长，保存一次就卡几秒，写作节奏全被打断了。需要编译的时候手动按Ctrl + Alt + B（macOS 是Cmd + Alt + B）就好，顺手又可控。

view.pdf.viewer设置成tab，表示在 VSCode 内部标签页预览 PDF，这也是我推荐的预览方式。改成browser会在系统浏览器打开，external则调用外部 PDF 阅读器。内部 tab 的好处是预览和源码在同一个窗口里，正反搜索操作起来最顺手。synctex.afterBuild.enabled打开之后，编译完会自动把 PDF 定位到光标所在源码对应的位置，虽然偶尔会跳不准，但大多时候很省事。

clean.fileTypes列了那些编译过程中产生的临时文件扩展名，比如.aux、.log、.synctex.gz。你随时可以在 VSCode 命令面板里执行LaTeX Workshop: Clean auxiliary files来清理。这里要注意，清理列表里千万不要加*.pdf，否则会把编译成果也删了，我就见过有人把*.pdf加进去，结果每次清理完都要重编一遍。

2.4 为什么第一个 recipe 我放 latexmk

很多教程的第一 recipe 是 xelatex，我的默认则是 latexmk，这不是顺手写的，而是因为它能解决 LaTeX 用户最头疼的一个问题：编译次数。

LaTeX 的编译机制决定了它需要多次编译才能让交叉引用、目录、参考文献全部正确。第一次编译把信息写进.aux文件，第二次编译读取这些信息生成正确的引用链接，参考文献还要额外跑一遍 BibTeX。如果你手动控制顺序，写一小节就得多按几次编译按钮，非常容易漏。

latexmk 是个 Perl 写的调度器，它自己不排版，但它会监视编译过程中生成的辅助文件，自动判断还需要再跑几遍编译器，以及是否需要调用 BibTeX、MakeIndex 等工具。也就是说，latexmk (xelatex)这个 recipe 在绝大多数情况下能一步到位，你不用管到底编译了几次。这就是标题里说的“一步完美解决”的真实含义：把需要人脑记住的编译顺序问题，交给工具去判断。

3. 多文件项目与正反搜索：把“编译主文件”这件事彻底理顺

配置完成后，大部分单文件文档已经能正常编译了。但论文、书籍这类项目通常会把内容拆成多个.tex文件，这时如果只是机械地按编译按钮，会触发另一类问题：插件找不到主文件。

3.1 插件怎么找到主文件

LaTeX Workshop 判断根文件有一套规则：优先处理% !TEX root魔法注释指定的文件，如果没有，就查找当前打开文件的同级和上级目录中带有\documentclass的那个文件，如果找到多个，会弹出选择框让你选。

问题往往出在多文件结构上。比如你的主文件叫main.tex，在根目录；每个章节放在chapters/chapter1.tex。当你打开chapter1.tex并按编译，插件可能会把chapter1.tex当作根文件来编译，结果它里面没有\documentclass，编译直接报错。解决的办法是在每个子文件的第一行加上一行注释：

% !TEX root = ../main.tex

这样无论你打开哪个章节文件，插件都会顺着这个路径找到主文件，然后编译主文件。这个习惯我从第一次写多章节论文就开始用，之后再也没有出现过“打开子文件就编译失败”的问题。

顺带说一句，多文件项目里的图片路径也经常让人困惑。LaTeX 在解析\includegraphics{figures/xxx.png}时，相对路径是相对于主文件所在目录的，而不是当前子文件所在目录。所以如果图片报找不到，第一反应应该是检查路径是否相对主文件目录，或者直接在导言区用\graphicspath{{figures/}}声明全局图片目录，能省很多事。

3.2 magic comment：一行注释解决一半问题

上面提到的% !TEX root是一种魔法注释，LaTeX Workshop 还支持另一种更重要的魔法注释：% !TEX program。它可以写在主文件顶部，用来指定编译这个文档应该用哪个程序。比如：

% !TEX program = xelatex \documentclass[UTF8]{ctexart} \begin{document} 中文测试 \end{document}

当你写了这一行后，插件会把 xelatex 作为默认编译器来处理。如果你的文档有特殊要求，比如不用 xelatex 而用 lualatex，也可以直接改 program 的取值。

不过魔法注释和 recipe 的优先级关系容易让人混淆。简单说：如果你在命令面板里手动选择了某个 recipe，插件以手动选择为准；如果没选，插件会参考 magic comment 指定的 program 来帮你挑一个合适的 recipe。所以最稳妥的做法是让魔法注释和默认 recipe 的引擎保持一致，别在注释里写 xelatex，recipe 里却用 pdflatex，那样很容易出现“看起来用 xelatex 编译了，实际跑的还是 pdflatex”的错觉。

3.3 SyncTeX 正反搜索的技巧

SyncTeX 是 LaTeX 编译时生成的一个反向索引机制，它能把 PDF 里的每一块内容和源码的行号对应起来。配合 VSCode 的预览面板，使用体验非常顺滑。

正向搜索（从源码到 PDF）：在.tex文件里把光标放到某一行，按下Ctrl + Alt + J（macOS 是Cmd + Alt + J），预览面板会跳到 PDF 中对应位置并高亮显示。反向搜索（从 PDF 到源码）：在 PDF 预览面板里按住Ctrl单击（macOS 是Cmd单击），源码编辑器会自动跳到对应行。写论文调整章节顺序、对照修改意见的时候，这两个操作能节省大量翻找时间。

如果发现正反搜索不生效，先检查编译参数里有没有-synctex=1。我在前面的配置里已经加上了，但如果魔法注释或者你后来改装了编译器，这个参数丢失，SyncTeX 文件就不会生成。另一个坑是外部 PDF 阅读器对 SyncTeX 支持参差不齐，如果你用的是 external 模式，跳转是否生效完全取决于那个阅读器，建议直接用内部 tab 模式，最省心。

4. 编译报错排查：从输出面板到根因的五类实战问题

配置再好，也绕不开报错。但报错其实是学习最快的路径，关键在于不要瞎试，而是有一套固定的排查链路。下面这五类是我在帮别人看电脑时遇到频率最高的，每个都附上完整的排查思路。

4.1 “Recipe terminated with fatal error”的完整排查链路

这句报错本身就是废话，它只告诉你“某个东西挂了”，没告诉你是什么。必须往下追。

第一步，打开 VSCode 的输出面板，把右上角的下拉菜单切到LaTeX Workshop频道。插件会把每次编译的详细日志写到这个频道里，这里能看到它实际执行的命令、返回码，以及具体的错误信息。

第二步，如果输出面板里显示的是spawn xelatex ENOENT，那基本就是环境变量的问题。这时回到终端，手动执行xelatex --version。如果终端也报找不到命令，说明 TeX Live 没装好或 PATH 没配好，回到第一章去检查安装。如果终端能用但 VSCode 里不能用，优先重启 VSCode，再确认你没用管理员身份启动。还有一个小概率情况是杀毒软件拦截了编译器进程，Windows Defender 有时会对 TeX Live 的二进制文件下手，把整个texlive\2024\bin目录加入白名单就好。

第三步，如果不是 ENOENT，而是某个 LaTeX 语法错误，比如! Undefined control sequence，那就翻.log文件。输出面板里通常有日志文件路径，打开它搜索!（感叹号加空格）开头的行，每一行都是一个错误，后面的英文描述才是真正值得研究的东西。

最后，如果错误信息里出现的宏包名字和你的模板对不上，比如模板用了ctexart，但你的安装缺了相关文件，那就是宏包缺失的问题，参考后文 4.5 来处理。

4.2 中文乱码、方块字和字体问题

中文乱码的根源在 90% 的情况下是编译引擎选错了。LaTeX 家族最早的 pdfTeX 对 CJK 支持非常别扭，需要配合CJK宏包和特定字体，处理起来既复杂又容易出问题。现在的标准做法是用 xelatex 配合ctex宏包，xelatex 直接调用系统中的字体，对 Unicode 的支持比 pdfTeX 好得多。

最小可编译的中文文档长这样：

\documentclass[UTF8,fontset=fandol]{ctexart} \begin{document} 你好，LaTeX。 \end{document}

编译引擎必须选择 xelatex，或者直接用前面的 latexmk recipe。如果你用 pdfLaTeX 去编译这个文件，大概率会得到一堆乱码或者直接报错。

fontset=fandol是一个值得解释的参数。ctex宏包在 Windows 上默认使用宋体、黑体等系统字体，在 macOS 上使用系统自带的中文字体，但在 Linux 或者字体不齐全的机器上，这些系统字体可能根本不存在，于是 xelatex 会报字体找不到的错误。fandol是一套随 TeX Live 分发的开源中文字体，不依赖操作系统，跨平台最稳。如果你在 Windows 上想用系统字体，可以显式写成fontset=windows；在 macOS 上可以写fontset=mac；图省事就用fandol，不管在哪台机器上编译结果都一致。

4.3 参考文献和交叉引用的“编译次数”问题

“明明\cite写对了，为什么编译后显示[?]？”这大概是 LaTeX 新手最爱问的问题之一。原因只有一个：编译次数不够。LaTeX 的引用机制是把信息写在.aux、.bbl等辅助文件里，第一次编译只是“记录信息”，要等到第二次编译才能把引用编号填进去。参考文献则更复杂，BibTeX 要先从.bib数据库里提取条目生成.bbl文件，然后再编译两遍才能全部稳定。

如果你用的是我前面配置里的 latexmk recipe，这个流程是自动完成的。如果你不幸在用那个“xelatex -> bibtex -> xelatex * 2”的手动 recipe，那就老老实实按顺序跑完，中途跳一步都会出问题。

排查时还要注意.bib文件的编码问题。BibTeX 很古老，对 UTF-8 的支持不算完美，如果.bib文件里出现编码不一致，或者用了奇怪的引号格式，日志里会出现I was expecting a \citation command之类的提示，这时优先检查.bib文件里的条目格式和编码。

4.4 PDF 预览失败、白屏与 SyncTeX 失效

PDF 文件编译成功，但 VSCode 预览面板白屏，这种情况多发生在插件版本更新后，或者项目路径包含中文、空格等特殊字符时。前端预览本质上是一个本地 web 服务，路径里的非 ASCII 字符偶尔会让它解析失败。解决方法是把项目放在纯英文路径下，这是最省事的方案，也顺便避免了很多其他工具的兼容问题。

如果白屏只在个别文件出现，试试把view.pdf.viewer临时切到browser，在系统浏览器里打开同一份 PDF，看看文件本身是否完好。浏览器能打开就说明 PDF 没问题，问题出在 VSCode 插件内部，重启窗口或更新插件通常能解决。浏览器也打不开，那就要看.log文件里有没有未捕获的错误，比如字体缺失或者图片崩溃。

SyncTeX 失效的场景我在 3.3 里已经讲过，这里再补一个容易忽略的细节：不要在编译完成后立刻修改源码行号，再马上去点 PDF 里的旧位置。.synctex.gz文件记录的是上次编译时的行列映射，源码改动后必须重新编译，跳转才是准确的，否则跳过去的位置永远是“上次编译时的状态”。

4.5 宏包缺失和其他零星报错

遇到! LaTeX Error: File 'xxx.sty' not found，说明某个宏包没装上。TeX Live 全量安装一般不会遇到，但如果你当初图省事装了精简版，或者在使用某个小众宏包，就需要手动补装：

tlmgr install 宏包名

tlmgr需要管理员权限，Windows 上请用管理员终端，macOS/Linux 则在命令前加sudo。如果tlmgr本身不可用，说明你的发行版不是官方 TeX Live，或者安装已经损坏，这时候与其折腾恢复，不如卸载后重新装一个全量版。

把高频报错汇总成一张表，方便你对照排查：

还有一类“报错”其实不是报错，比如日志里出现Overfull \hbox和Underfull \hbox，这只是在提醒你某些行的长度或间距不太理想，属于排版建议，不影响编译结果，不需要紧张。

5. 从能编译到好用：产物收纳、Git 协作和提速细节

编译跑通只是起点。真正让你的写作环境“好用”，还要处理编译产物的收纳问题。LaTeX 每编译一次，就会在项目目录里生成一堆.aux、.log、.toc、.synctex.gz之类的临时文件，文件夹里乱七八糟不说，往 Git 提交的时候如果不小心把这些文件推上去，还会污染仓库。

5.1 把编译产物收进 build 目录

如果你喜欢让项目根目录保持干净，可以在 settings.json 里加一行输出目录配置：

"latex-workshop.latex.outDir": "%DIR%/build"

加上之后，latexmk 的-outdir=%OUTDIR%会把 PDF 和所有辅助文件都生成到build子目录里。这个方案配合 latexmk recipe 使用效果很好，因为 latexmk 知道辅助文件在哪里。

但这里有一个要注意的坑：如果你换回那个“xelatex -> bibtex -> xelatex * 2”的手动 recipe，bibtex 默认会在当前工作目录找.aux文件，而辅助文件已经在build目录里了，结果 bibtex 会报找不到.aux。要么你改掉 outDir 配置，要么给 bibtex 工具加上明确指向输出目录的参数，比如args写成["%OUTDIR%/%DOCFILE%"]，让 bibtex 去 build 目录下处理。手动 recipe 配输出目录的细节比较繁琐，我的建议是：如果用输出目录方案，就老老实实走 latexmk 流程，别手动拆步骤。

如果不改 outDir，坚持默认输出到源文件目录，那就靠定期清理和.gitignore来维持整洁，这也是完全可行的方案。

5.2 自动编译与自动清理的取舍

自动编译这个功能，我的态度经历了一个从“必须开”到“关掉”的过程。刚配置好的时候，觉得每次保存自动编译特别酷，后来写长文档，光标一动就触发重编，风扇嗡嗡转，VSCode 的响应都变卡了，而且编译中的输出面板还会抢占注意力。最终我把autoBuild.run设置成了never，需要时用Ctrl + Alt + B手动编译。如果你觉得手动麻烦，可以接受一点延迟，设成onSave也行，但我建议大文档写作时关掉自动编译，人脑切换状态的成本远大于那一次快捷键。

清理命令也很重要。写一段时间之后，临时文件会堆积，尤其是.synctex.gz这类文件，不会自动消失。在命令面板执行LaTeX Workshop: Clean auxiliary files，插件会按clean.fileTypes列表删除临时文件。但注意，Windows 下如果 PDF 正被预览面板占用，清理时可能会出现文件被锁定的提示，这是正常现象，关掉 PDF 再清理就行。

5.3 编译慢，不一定是你电脑的错

LaTeX 编译本身不算快，但如果你觉得慢到离谱，先别急着怪电脑，检查几个外部因素。

杀毒软件是最常见的隐形杀手。Windows Defender 对项目目录和 TeX Live 安装目录的实时扫描，会对大量读写小文件的编译过程造成明显拖累。把 TeX Live 的安装目录和你写论文的项目目录加入排除列表，编译速度经常能快一倍。如果项目放在网络驱动器、云同步盘或者 U 盘上，编译也会变得异常缓慢，因为 LaTeX 编译要频繁读写辅助文件，网络磁盘的延迟会被放大。

另外要区分“首次编译慢”和“每次编译都慢”。xelatex 首次编译时需要加载字体并建立字形缓存，确实比较慢；第二次编译会重用缓存，速度快很多。如果项目每次编译都慢得离谱，看看日志里有没有反复加载同一套字体的痕迹，或者考虑换用fontset=fandol减小系统字体依赖。

5.4 用 .gitignore 管住辅助文件

如果你的项目用 Git 管理，强烈建议加入一份.gitignore，把 LaTeX 的辅助文件和 PDF 产物排除在外。模板可以直接抄：

build/ *.aux *.bbl *.blg *.fdb_latexmk *.fls *.log *.out *.synctex.gz *.toc *.lof *.lot *.nav *.snm *.vrb

如果你把产物收进了build/目录，忽略掉build/就够了，其余那些辅助文件本来就会进 build。如果保持默认输出目录，就靠后面的扩展名规则来挡。PDF 要不要忽略看协作习惯，个人写作建议忽略，因为 PDF 是编译产物，随时能重新生成，没必要进版本库增加冲突概率；但如果团队里有非 LaTeX 用户，需要直接看 PDF 评审，那就保留并定期更新，视情况而定。

我在实际使用中，把这套配置同步到了一个配置文件仓库里，换新电脑时安装 TeX Live、装上 LaTeX Workshop 插件，再把这份 settings.json 覆盖进去，三分钟就能回到熟悉的编译环境。如果你也经常在多台设备间切换，很值得一试。最后再分享一个小经验：遇到编译问题的时候，先把输出面板切到 LaTeX Workshop 频道，再复制完整日志去搜索，远比只搜索那句"Recipe terminated with fatal error"有效得多——那种泛泛的报错在网上能找到一万个不重样的解答，而你的具体问题只藏在日志的细节里。