拖了好几年我终于把写毕业论文的战场从 Overleaf 彻底搬回了 VsCode。不是因为网页版不好用而是当文档越来越长、章节越来越多我在本地反复编译时根目录里堆满了.aux、.log、.toc这些中间文件看着就烦躁。更让人抓狂的是PDF 和源文件混在一起想单独拷贝一份编译结果都费劲。后来花了半天时间研究 LaTeX 编译环境的配置逻辑终于把指定输出目录这件事彻底搞明白了。这篇东西不打算讲那种照着抄就能跑的玄学教程而是把我从环境搭建、配置理解、踩坑排错到最终顺手用的完整过程写下来。适合三类人刚接触 LaTeX 想在本机写论文的初学者、已经装了 VsCode 但被各种报错折磨到想砸电脑的人以及想优化工作目录结构、让编译产物不再乱飞的进阶用户。如果你准备好了我们直接开工。1. 动工之前先把 TeX 发行版和 VSCode 插件这两样地基打牢很多人配置 LaTeX 环境的第一步就是跑去 VsCode 装插件装完之后发现编译按钮点了没反应于是开始怀疑人生。这里必须强调一句VSCode 的 LaTeX Workshop 插件本质上只是一个遥控器真正负责把.tex编译成.pdf的是你安装在操作系统里的 TeX 发行版。顺序搞反了后面全是坑。1.1 TeX Live 还是 MiKTeX按你的硬盘和网络条件选主流的 TeX 发行版有三个TeX Live、MiKTeX 和 MacTeX。Windows 用户基本就在 TeX Live 和 MiKTeX 之间纠结macOS 用户则直接上 MacTeX因为底层就是 TeX Live 的 macOS 版本没什么好犹豫的。我个人的选择是 TeX Live 2024理由比较实在一次性安装完整宏包后续不会出现编译到一半提示缺少宏包被迫联网下载的尴尬。离线可用性强写论文期间不依赖网络稳定性有保障。和 LaTeX Workshop 默认调用的 latexmk 配合非常默契。但 TeX Live 的缺点是安装包体积巨大完整安装要占用好几个 GB 磁盘空间下载也要花不少时间。如果你的磁盘比较紧张或者网速一般MiKTeX 反而更合适。MiKTeX 的特点是按需自动安装宏包第一次编译某篇文档时发现缺包它会自动下载补上体感上轻量很多。缺点是每次缺包都要等下载而且宏包缓存越滚越大需要定期清理。这里有个容易被忽略的细节不管装哪个发行版安装完成后一定要确认系统的 PATH 环境变量里已经包含了它的可执行目录。验证方法很简单打开终端输入latexmk --version xelatex --version如果都能正常输出版本信息说明发行版已经就绪。我在实际配置过程中遇到过太多次VSCode 提示找不到 latexmk但终端里明明能用的情况绝大多数都是 VSCode 没有重新加载环境变量导致的。1.2 为什么我推荐 LaTeX Workshop 而不是其他插件VSCode 插件市场里和 LaTeX 相关的插件其实有几个但真正称得上全家桶的只有 James Yu 开发的 LaTeX Workshop。它把编辑辅助、语法高亮、编译、PDF 预览、正向反向同步全都整合在了一套 UI 里用熟了之后你根本不需要在多个插件之间来回切换。安装步骤没什么特殊的打开 VSCode 扩展商店搜索LaTeX Workshop认准作者为 James Yu 的那个点击安装然后重新加载窗口即可。需要提醒的是LaTeX Workshop 不会主动帮你安装 TeX 发行版。如果你在插件安装完成后打开.tex文件发现界面下方显示类似 Recipe terminated with fatal error 的错误信息九成是发行版没装好或者 PATH 没生效别急着怀疑插件本身。1.3 用最小示例验证基础编译链路配置环境最忌讳一上来就搞复杂模板。我的习惯是先建一个干净的测试目录新建main.tex写入最简单的文档骨架\documentclass{article} \begin{document} Hello, VsCode and LaTeX! \end{document}然后在编辑器右上角找到▶按钮或者打开侧边栏 LaTeX 面板点击Build LaTeX project。正常情况下几秒后同目录下会生成main.pdf同时出现.aux、.log等辅助文件。走到这一步说明地基已经牢固接下来才能真正开始折腾输出目录的问题。2. 为什么默认配置会让编译产物乱成一团先别急着改配置文件。如果你不清楚 LaTeX 编译过程到底产生了哪些文件以及 latexmk 在其中扮演什么角色那么指定输出目录就只是一个抄来的配置片段出了问题你根本无从下手。2.1 辅助文件清单它们不是垃圾而是必需品我第一次看到一个.tex文件编译后生成一堆乱七八糟的后缀文件时第一反应是LaTeX 太不讲究了。后来才知道这是 LaTeX 的工作原理决定的。简单列一下最常见的辅助文件及其用途文件后缀用途.aux记录交叉引用、目录项、书签信息编译下一轮时会被再次读取.log编译日志记录了所有警告、报错、字体信息和排版进度.toc保存目录结构两次编译之间传递数据.out生成 PDF 书签hyperref 宏包使用.bbl/.blg处理 BibTeX 参考文献时的中间产物和日志.synctex.gz源码与 PDF 之间的位置映射实现双向同步跳转.fls/.fdb_latexmklatexmk 记录的文件依赖关系用于判断下次编译是否需要增量更新这些文件不是可有可无的垃圾。交叉引用之所以需要编译两遍才能正确显示页码就是因为第一遍.aux还没生成第二遍才能读取前一轮的结果。如果强行删除编译就会从零开始不仅速度变慢还有可能引入莫名其妙的引用错误。理解了这一点你就会明白与其想着消除辅助文件不如把它们和最终 PDF 一起统一挪到一个单独的目录里。2.2 latexmk 才是真正干活的调度员VSCode 里的 LaTeX Workshop 默认会调用latexmk这条编译工具链。很多人对 latexmk 的认知是一个 LaTeX 编译器其实不是。它是一个用 Perl 写的自动化调度脚本它的工作类似于一个包工头检查主文档的依赖关系判断需要运行多少次pdflatex、xelatex、biber才能让交叉引用稳定在所有编译轮次结束后生成最终 PDF。举个直观的例子一篇包含参考文献和交叉引用的论文手动编译至少需要编译 → 文献处理 → 再编译 → 再编译好几轮。latexmk 会自动完成这个过程你只需要给它一个编译引擎参数它就会把该跑的都跑完。那么指定输出目录这件事最终落在哪个环节上答案是 latexmk 的命令行参数-outdir目录。这个参数告诉 latexmk所有中间产物和最终 PDF都生成到指定目录下。2.3 VSCode 的 outDir 与 latexmk 的 -outdir 是两回事新手最容易踩的坑就在这里。LaTeX Workshop 里有一个叫latex-workshop.latex.outDir的设置项光看名字你会觉得设成 build 就完事了。但如果你只改这个不修改 tools 配置里传给 latexmk 的参数那么实际编译时 latexmk 根本不会把文件输出到 build 目录PDF 还是会生成在源文件所在目录。这里有一个重要的认知插件的 outDir 只是一个期望目标真正驱动输出位置的是编译工具参数-outdir%OUTDIR%。LaTeX Workshop 会把%OUTDIR%这个占位符替换成你要的目录名然后传给 latexmk。如果工具参数里没有这个占位符插件压根不会知道 latexmk 该把 PDF 放到哪里去。我把两张配置同步检查作为指定输出目录的黄金准则settings.json 里必须同时看到outDir和-outdir%OUTDIR%两者缺一不可。3. 亲手写一份能把文件输出到独立目录的完整配置下面这份配置我在 Windows、macOS 上都跑通过了可以直接复制到你的工作区设置里。为了便于讲解我假设你想让所有编译产物进入源文件目录下的build文件夹。3.1 一份最小可用的 settings.json在 VSCode 里按下CtrlShiftP输入Preferences: Open Workspace Settings打开工作区设置。如果你希望所有 LaTeX 项目都使用这套配置就打开用户设置。然后把下面的内容放进去{ latex-workshop.latex.tools: [ { name: latexmk, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, -outdir%OUTDIR%, %DOC% ], env: {} } ], latex-workshop.latex.recipes: [ { name: latexmk, tools: [latexmk] } ], latex-workshop.latex.outDir: build, latex-workshop.latex.autoBuild.run: onSave, latex-workshop.view.pdf.viewer: tab }改完之后别忘记重新加载窗口CtrlShiftP→Reload Window。然后再次编译你的测试文档你会看到build目录自动出现里面整整齐齐躺着main.pdf和所有辅助文件。3.2 配置里的每个字段都在干什么上面的配置不长但每个键都有它存在的理由我拆开讲一遍。latex-workshop.latex.tools定义了一组可用的编译工具。这里声明了一个叫latexmk的工具command指定了要执行的命令args是命令参数。%DOC%是 LaTeX Workshop 提供的内置占位符会被替换为当前打开的.tex文件的完整路径。-pdf让 latexmk 调用 pdflatex 生成 PDF如果你用 XeLaTeX 处理中文文档需要把它替换成-xelatex或者在 args 里直接改成-pdfxe。我建议中文用户一开始就考虑用 XeLaTeX因为现代模板大多基于ctex宏包对中文支持更友好。-synctex1会生成.synctex.gz文件这个文件是实现 VSCode 和 PDF 双向同步跳转的关键。-interactionnonstopmode的意思是遇到错误不要停下等待用户交互直接以非交互模式推进这样 LaTeX Workshop 才能自动获取编译结果。-file-line-error让报错信息带上具体的文件路径和行号方便你在输出面板里快速定位问题。latex-workshop.latex.recipes定义了配方也就是一次编译要按顺序执行哪些工具。这里只有一个工具latexmk因为 latexmk 本身已经够聪明不需要额外串联其他命令。latex-workshop.latex.outDir就是我们要指定的输出目录值为build。LaTeX Workshop 会把这个值替换进每个%OUTDIR%占位符。值得注意的一点是这里的路径是相对于工作区根目录而言的不需要以/开头也不要带尾斜杠。latex-workshop.latex.autoBuild.run控制自动编译时机。onSave表示每次保存.tex文件就自动编译一次适合写论文时依赖实时预览的场景。如果你觉得每次保存都编译太卡可以改成never然后手动点击编译按钮。最后一个latex-workshop.view.pdf.viewer指定 PDF 预览方式。tab表示在 VSCode 内置的 PDF 预览标签页中打开如果你想用外部 PDF 阅读器可以填external但那样就需要配置额外的命令行参数我后面会提到。3.3 Windows、macOS 与 Linux 的路径差异这套配置在三个系统上基本通用但有几处细节我劝你提前注意。Windows 上VSCode 和 LaTeX Workshop 对正斜杠/的兼容性很好所以build这种写法完全没问题。真正的问题出在中文路径和空格路径上。如果你的用户名是中文或者工作区目录放在了一个含有空格的路径下latexmk 在解析文件路径时很可能出现奇怪的报错比如找不到文件、生成文件位置不对甚至编译直接中断。这不是你配置写错了而是底层工具链对非 ASCII 路径的支持参差不齐。最稳妥的方案是把所有 LaTeX 项目放在像D:\texworks或~/latex这样的纯英文路径下。macOS 和 Linux 基本没有这个困扰正斜杠天然统一。唯一要注意的是权限问题如果build目录被创建在工作区之外latexmk 可能没有写入权限。保持目录在工作区内最省心。如果你使用 WSL 远程开发情况会复杂一些。LaTeX Workshop 运行在 Windows 侧但 TeX 发行版装在 WSL 里路径映射和%OUTDIR%的解析都可能出问题。我的建议是直接用 WSL 的 Remote 模式打开工作区让整个工具链都跑在同一套文件系统里不要做跨系统混搭。3.4 配置完成后的验证动作配置生效不是改一个 JSON 就行的很多修改需要重载窗口才能被插件读取。完成上述步骤后我建议按这个顺序验证CtrlShiftP→Reload Window。打开main.tex按下CtrlS。观察底部输出面板中的编译日志。确认build目录出现并且main.pdf在里面。点击 PDF 预览标签确认内容正常显示。如果第 4 步失败PDF 还是出现在源目录请回到第 3.2 节检查args里是否写了-outdir%OUTDIR%。这个细节决定了整个方案是否成立。4. 输出目录改完真正的坑才刚开始配置好输出目录只是第一步。接下来你会遇到几个新问题基本都和 PDF 预览、Synctex、辅助文件清理有关。我一个个说。4.1 内置 PDF 预览为什么找不到文件LaTeX Workshop 的内置 PDF 查看器在定位 PDF 时会优先读取outDir设置。只要outDir正确插件会去build目录里找 PDF 并打开所以大部分情况下内置预览是免配置的。但如果你之前手动改过latex-workshop.view.pdf.viewer或者使用过某些旧版配置模板插件可能仍然去源目录找 PDF。这种情况的典型表现是编译成功、build目录里也有 PDF但点击预览按钮提示文件不存在。排查思路很简单确认outDir存在确认 PDF 真的在这个目录里然后重新加载窗口。如果还没解决可以把 viewer 设置先调整为tab试试排除外部预览器的干扰。4.2 点击 PDF 跳不回源码反向同步失效了Synctex 是 LaTeX 生态里一个很实用的功能在 VSCode 里Ctrl点击可以跳转到 PDF 对应位置在 PDF 里Ctrl点击又能跳回源码。但指定输出目录后反向同步偶尔会失灵。根本原因通常是.synctex.gz没有生成或者它的位置与插件预期不一致。请检查两处编译参数里是否带了-synctex1。如果用的不是 latexmk而是直接调用 xelatex很容易漏掉这个参数。build目录下是否存在main.synctex.gz文件。如果存在插件理论上会自动识别。如果文件存在但同步还是失败可以检查一下.tex文件编码是否为 UTF-8以及路径里是否包含中文。我在实践中发现部分版本的 Synctex 对非 UTF-8 路径的解析很脆弱与其花时间调它不如把项目路径改成纯英文一劳永逸。4.3 辅助文件清理别再把源目录清空了输出目录已经统一到build了源目录干净了但build里的辅助文件还是会越积越多。LaTeX Workshop 提供了清理功能可以自定义清理规则。我目前的清理配置长这样latex-workshop.latex.clean: [ build/*.aux, build/*.log, build/*.toc, build/*.out, build/*.synctex.gz, build/*.fls, build/*.fdb_latexmk ]注意这个列表是针对工作区根目录的 glob 匹配。如果你的 outDir 不是build需要同步修改前缀。每次编译后可以在 LaTeX 侧边栏点击Clean auxiliary files手动清理也可以配合latexmk -c命令安全清理。这里不推荐用latexmk -C因为它会把最终 PDF 也删掉别问我是怎么知道的。5. 从编译失败到日志定位一条完整的排错链路无论配置写得多完美总会有翻车的时候。下面这段是我在一台新电脑上真实经历过的排错过程用的方法你完全可以照搬。5.1 一次真实的故障复现当时我刚换了工作电脑重新安装 TeX Live 2024并把 VSCode 配置文件和以前一样复制过来。结果打开测试工程后一点编译按钮输出面板直接甩给我一行Recipe terminated with fatal error: spawn latexmk ENOENT这句话翻译过来是VSCode 尝试启动latexmk这个进程但系统根本找不到这个可执行文件。换成大白话说遥控器已经按下了但电视机没开机。我当时的第一反应是TeX Live 没装好于是重新运行安装程序折腾了半天无果。最后发现问题出在环境变量上TEX Live 的安装程序已经把路径写进了系统 PATH但 VSCode 是在 PATH 更新之前启动的它根本没来得及刷新环境变量。解决办法出奇简单完全关闭 VSCode 再重新打开。这里我总结一个实用原则在 VSCode 里遇到ENOENT、spawn ... failed这类错误优先怀疑 PATH 和环境变量而不是怀疑配置本身。很多工具链问题都出在程序能启动但命令找不到这个环节。5.2 日志文件应该怎么看当编译失败时你的第一反应不应该是反复点编译按钮而是去看日志。LaTeX Workshop 的输出面板入口在菜单栏视图 → 输出然后在右上角的下拉框里选择LaTeX Workshop。日志里最有价值的是最后几十行通常包含两类信息工具调用过程比如 latexmk 实际执行的命令行是什么。报错的具体位置比如./main.tex:12: Undefined control sequence.这说明main.tex第 12 行有一个宏命令没定义。有些错误是 LaTeX 自身的语法错误VSCode 侧边栏不会显示只有build/main.log里才写得很详细。打开build目录下的.log文件搜索关键字!通常能定位到真正的崩溃点。学会看这两份日志能帮你省下一大半求人问问题的时间。5.3 中文路径导致的玄学报错我见过不少用户用中文用户名创建了自己的 Windows 账户然后把项目文件放在文档里结果编译报错后大喊LaTeX 太垃圾了。实际上这是路径处理的问题。当 latexmk 收到一个包含中文或空格的路径时不同的命令解析方式会产生歧义。比如xelatex对中文路径的兼容性时好时坏。.synctex.gz文件在中文路径下可能无法正常生成。某些宏包在读取文件时对路径中的非 ASCII 字符处理不当。最省心的做法是新建一个纯英文路径的工作区比如C:\tex\paper或~/latex/paper确认无中文、无空格、无特殊符号。这个方法虽然看起来土但确实能避免一大批坑。5.4 多文件项目谁才是根文件当你的论文拆分成多个.tex文件比如main.tex、chapter1.tex、chapter2.texLaTeX Workshop 在编译时需要一个明确的根文件。如果你打开的是chapter1.tex再点编译插件可能会尝试把这个子文件当作独立文档去编译结果当然是一堆未定义引用和报错。两种主流解决办法在工作区设置里指定根文件latex-workshop.latex.rootFile: main.tex在每个子文件头部写魔法注释% !TeX root main.tex我比较推荐第二种方式因为这种代码具有可移植性换个环境不需要重新配置。而且当你在子文件里时LaTeX Workshop 会自动识别魔法注释直接编译正确的根文件非常顺手。6. 我一直在用的几个配置细节顺便给你提个醒到了这一步你的 VsCode LaTeX 环境已经能稳定工作并指定输出目录了。最后分享几个我在实际使用中沉淀下来的习惯它们不一定会让你的编译速度发生质变但会让日常体验舒服很多。第一个是自动清理的开关。如果你希望每次编译完成后顺手把中间产物删掉可以把latex-workshop.latex.autoClean.run设置为onBuilt。这样每次成功构建后插件都会按照你配置的清理规则删除辅助文件。我自己不会开这个开关因为我经常需要查看.log文件调排版但如果你的项目结构很标准、出问题频率低开着确实能让目录非常清爽。第二个是用 XeLaTeX 处理中文。如果你要写中文论文、带中文书签或者用ctex宏包强烈建议把编译工具改成args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, -outdir%OUTDIR%, %DOC% ]改动的地方只有一个把-pdf换成-xelatex其他的保持不变。latexmk 会自动调用 xelatex并且同样能把所有文件输出到build目录。第三个是备份配置。settings.json是你整个 LaTeX 环境的精髓我建议把它单独存一份到自己的代码仓库或云笔记里换新电脑时直接粘贴即可。我在写这篇内容时用的正是那份备份配置从头到尾没踩过一个多余的大坑。最后再提一个细节如果你在配置过程中遇到了某个报错先别急着复制搜索引擎里的标准答案先看一眼实际的报错语句和日志。配置 LaTeX 环境这件事最重要的不是记住某一段 JSON而是理解outDir和-outdir之间的映射关系。搞懂了这一环剩下的不过是锦上添花。
拖了好几年我终于把写毕业论文的战场从 Overleaf 彻底搬回了 VsCode。不是因为网页版不好用而是当文档越来越长、章节越来越多我在本地反复编译时根目录里堆满了.aux、.log、.toc这些中间文件看着就烦躁。更让人抓狂的是PDF 和源文件混在一起想单独拷贝一份编译结果都费劲。后来花了半天时间研究 LaTeX 编译环境的配置逻辑终于把指定输出目录这件事彻底搞明白了。这篇东西不打算讲那种照着抄就能跑的玄学教程而是把我从环境搭建、配置理解、踩坑排错到最终顺手用的完整过程写下来。适合三类人刚接触 LaTeX 想在本机写论文的初学者、已经装了 VsCode 但被各种报错折磨到想砸电脑的人以及想优化工作目录结构、让编译产物不再乱飞的进阶用户。如果你准备好了我们直接开工。1. 动工之前先把 TeX 发行版和 VSCode 插件这两样地基打牢很多人配置 LaTeX 环境的第一步就是跑去 VsCode 装插件装完之后发现编译按钮点了没反应于是开始怀疑人生。这里必须强调一句VSCode 的 LaTeX Workshop 插件本质上只是一个遥控器真正负责把.tex编译成.pdf的是你安装在操作系统里的 TeX 发行版。顺序搞反了后面全是坑。1.1 TeX Live 还是 MiKTeX按你的硬盘和网络条件选主流的 TeX 发行版有三个TeX Live、MiKTeX 和 MacTeX。Windows 用户基本就在 TeX Live 和 MiKTeX 之间纠结macOS 用户则直接上 MacTeX因为底层就是 TeX Live 的 macOS 版本没什么好犹豫的。我个人的选择是 TeX Live 2024理由比较实在一次性安装完整宏包后续不会出现编译到一半提示缺少宏包被迫联网下载的尴尬。离线可用性强写论文期间不依赖网络稳定性有保障。和 LaTeX Workshop 默认调用的 latexmk 配合非常默契。但 TeX Live 的缺点是安装包体积巨大完整安装要占用好几个 GB 磁盘空间下载也要花不少时间。如果你的磁盘比较紧张或者网速一般MiKTeX 反而更合适。MiKTeX 的特点是按需自动安装宏包第一次编译某篇文档时发现缺包它会自动下载补上体感上轻量很多。缺点是每次缺包都要等下载而且宏包缓存越滚越大需要定期清理。这里有个容易被忽略的细节不管装哪个发行版安装完成后一定要确认系统的 PATH 环境变量里已经包含了它的可执行目录。验证方法很简单打开终端输入latexmk --version xelatex --version如果都能正常输出版本信息说明发行版已经就绪。我在实际配置过程中遇到过太多次VSCode 提示找不到 latexmk但终端里明明能用的情况绝大多数都是 VSCode 没有重新加载环境变量导致的。1.2 为什么我推荐 LaTeX Workshop 而不是其他插件VSCode 插件市场里和 LaTeX 相关的插件其实有几个但真正称得上全家桶的只有 James Yu 开发的 LaTeX Workshop。它把编辑辅助、语法高亮、编译、PDF 预览、正向反向同步全都整合在了一套 UI 里用熟了之后你根本不需要在多个插件之间来回切换。安装步骤没什么特殊的打开 VSCode 扩展商店搜索LaTeX Workshop认准作者为 James Yu 的那个点击安装然后重新加载窗口即可。需要提醒的是LaTeX Workshop 不会主动帮你安装 TeX 发行版。如果你在插件安装完成后打开.tex文件发现界面下方显示类似 Recipe terminated with fatal error 的错误信息九成是发行版没装好或者 PATH 没生效别急着怀疑插件本身。1.3 用最小示例验证基础编译链路配置环境最忌讳一上来就搞复杂模板。我的习惯是先建一个干净的测试目录新建main.tex写入最简单的文档骨架\documentclass{article} \begin{document} Hello, VsCode and LaTeX! \end{document}然后在编辑器右上角找到▶按钮或者打开侧边栏 LaTeX 面板点击Build LaTeX project。正常情况下几秒后同目录下会生成main.pdf同时出现.aux、.log等辅助文件。走到这一步说明地基已经牢固接下来才能真正开始折腾输出目录的问题。2. 为什么默认配置会让编译产物乱成一团先别急着改配置文件。如果你不清楚 LaTeX 编译过程到底产生了哪些文件以及 latexmk 在其中扮演什么角色那么指定输出目录就只是一个抄来的配置片段出了问题你根本无从下手。2.1 辅助文件清单它们不是垃圾而是必需品我第一次看到一个.tex文件编译后生成一堆乱七八糟的后缀文件时第一反应是LaTeX 太不讲究了。后来才知道这是 LaTeX 的工作原理决定的。简单列一下最常见的辅助文件及其用途文件后缀用途.aux记录交叉引用、目录项、书签信息编译下一轮时会被再次读取.log编译日志记录了所有警告、报错、字体信息和排版进度.toc保存目录结构两次编译之间传递数据.out生成 PDF 书签hyperref 宏包使用.bbl/.blg处理 BibTeX 参考文献时的中间产物和日志.synctex.gz源码与 PDF 之间的位置映射实现双向同步跳转.fls/.fdb_latexmklatexmk 记录的文件依赖关系用于判断下次编译是否需要增量更新这些文件不是可有可无的垃圾。交叉引用之所以需要编译两遍才能正确显示页码就是因为第一遍.aux还没生成第二遍才能读取前一轮的结果。如果强行删除编译就会从零开始不仅速度变慢还有可能引入莫名其妙的引用错误。理解了这一点你就会明白与其想着消除辅助文件不如把它们和最终 PDF 一起统一挪到一个单独的目录里。2.2 latexmk 才是真正干活的调度员VSCode 里的 LaTeX Workshop 默认会调用latexmk这条编译工具链。很多人对 latexmk 的认知是一个 LaTeX 编译器其实不是。它是一个用 Perl 写的自动化调度脚本它的工作类似于一个包工头检查主文档的依赖关系判断需要运行多少次pdflatex、xelatex、biber才能让交叉引用稳定在所有编译轮次结束后生成最终 PDF。举个直观的例子一篇包含参考文献和交叉引用的论文手动编译至少需要编译 → 文献处理 → 再编译 → 再编译好几轮。latexmk 会自动完成这个过程你只需要给它一个编译引擎参数它就会把该跑的都跑完。那么指定输出目录这件事最终落在哪个环节上答案是 latexmk 的命令行参数-outdir目录。这个参数告诉 latexmk所有中间产物和最终 PDF都生成到指定目录下。2.3 VSCode 的 outDir 与 latexmk 的 -outdir 是两回事新手最容易踩的坑就在这里。LaTeX Workshop 里有一个叫latex-workshop.latex.outDir的设置项光看名字你会觉得设成 build 就完事了。但如果你只改这个不修改 tools 配置里传给 latexmk 的参数那么实际编译时 latexmk 根本不会把文件输出到 build 目录PDF 还是会生成在源文件所在目录。这里有一个重要的认知插件的 outDir 只是一个期望目标真正驱动输出位置的是编译工具参数-outdir%OUTDIR%。LaTeX Workshop 会把%OUTDIR%这个占位符替换成你要的目录名然后传给 latexmk。如果工具参数里没有这个占位符插件压根不会知道 latexmk 该把 PDF 放到哪里去。我把两张配置同步检查作为指定输出目录的黄金准则settings.json 里必须同时看到outDir和-outdir%OUTDIR%两者缺一不可。3. 亲手写一份能把文件输出到独立目录的完整配置下面这份配置我在 Windows、macOS 上都跑通过了可以直接复制到你的工作区设置里。为了便于讲解我假设你想让所有编译产物进入源文件目录下的build文件夹。3.1 一份最小可用的 settings.json在 VSCode 里按下CtrlShiftP输入Preferences: Open Workspace Settings打开工作区设置。如果你希望所有 LaTeX 项目都使用这套配置就打开用户设置。然后把下面的内容放进去{ latex-workshop.latex.tools: [ { name: latexmk, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, -outdir%OUTDIR%, %DOC% ], env: {} } ], latex-workshop.latex.recipes: [ { name: latexmk, tools: [latexmk] } ], latex-workshop.latex.outDir: build, latex-workshop.latex.autoBuild.run: onSave, latex-workshop.view.pdf.viewer: tab }改完之后别忘记重新加载窗口CtrlShiftP→Reload Window。然后再次编译你的测试文档你会看到build目录自动出现里面整整齐齐躺着main.pdf和所有辅助文件。3.2 配置里的每个字段都在干什么上面的配置不长但每个键都有它存在的理由我拆开讲一遍。latex-workshop.latex.tools定义了一组可用的编译工具。这里声明了一个叫latexmk的工具command指定了要执行的命令args是命令参数。%DOC%是 LaTeX Workshop 提供的内置占位符会被替换为当前打开的.tex文件的完整路径。-pdf让 latexmk 调用 pdflatex 生成 PDF如果你用 XeLaTeX 处理中文文档需要把它替换成-xelatex或者在 args 里直接改成-pdfxe。我建议中文用户一开始就考虑用 XeLaTeX因为现代模板大多基于ctex宏包对中文支持更友好。-synctex1会生成.synctex.gz文件这个文件是实现 VSCode 和 PDF 双向同步跳转的关键。-interactionnonstopmode的意思是遇到错误不要停下等待用户交互直接以非交互模式推进这样 LaTeX Workshop 才能自动获取编译结果。-file-line-error让报错信息带上具体的文件路径和行号方便你在输出面板里快速定位问题。latex-workshop.latex.recipes定义了配方也就是一次编译要按顺序执行哪些工具。这里只有一个工具latexmk因为 latexmk 本身已经够聪明不需要额外串联其他命令。latex-workshop.latex.outDir就是我们要指定的输出目录值为build。LaTeX Workshop 会把这个值替换进每个%OUTDIR%占位符。值得注意的一点是这里的路径是相对于工作区根目录而言的不需要以/开头也不要带尾斜杠。latex-workshop.latex.autoBuild.run控制自动编译时机。onSave表示每次保存.tex文件就自动编译一次适合写论文时依赖实时预览的场景。如果你觉得每次保存都编译太卡可以改成never然后手动点击编译按钮。最后一个latex-workshop.view.pdf.viewer指定 PDF 预览方式。tab表示在 VSCode 内置的 PDF 预览标签页中打开如果你想用外部 PDF 阅读器可以填external但那样就需要配置额外的命令行参数我后面会提到。3.3 Windows、macOS 与 Linux 的路径差异这套配置在三个系统上基本通用但有几处细节我劝你提前注意。Windows 上VSCode 和 LaTeX Workshop 对正斜杠/的兼容性很好所以build这种写法完全没问题。真正的问题出在中文路径和空格路径上。如果你的用户名是中文或者工作区目录放在了一个含有空格的路径下latexmk 在解析文件路径时很可能出现奇怪的报错比如找不到文件、生成文件位置不对甚至编译直接中断。这不是你配置写错了而是底层工具链对非 ASCII 路径的支持参差不齐。最稳妥的方案是把所有 LaTeX 项目放在像D:\texworks或~/latex这样的纯英文路径下。macOS 和 Linux 基本没有这个困扰正斜杠天然统一。唯一要注意的是权限问题如果build目录被创建在工作区之外latexmk 可能没有写入权限。保持目录在工作区内最省心。如果你使用 WSL 远程开发情况会复杂一些。LaTeX Workshop 运行在 Windows 侧但 TeX 发行版装在 WSL 里路径映射和%OUTDIR%的解析都可能出问题。我的建议是直接用 WSL 的 Remote 模式打开工作区让整个工具链都跑在同一套文件系统里不要做跨系统混搭。3.4 配置完成后的验证动作配置生效不是改一个 JSON 就行的很多修改需要重载窗口才能被插件读取。完成上述步骤后我建议按这个顺序验证CtrlShiftP→Reload Window。打开main.tex按下CtrlS。观察底部输出面板中的编译日志。确认build目录出现并且main.pdf在里面。点击 PDF 预览标签确认内容正常显示。如果第 4 步失败PDF 还是出现在源目录请回到第 3.2 节检查args里是否写了-outdir%OUTDIR%。这个细节决定了整个方案是否成立。4. 输出目录改完真正的坑才刚开始配置好输出目录只是第一步。接下来你会遇到几个新问题基本都和 PDF 预览、Synctex、辅助文件清理有关。我一个个说。4.1 内置 PDF 预览为什么找不到文件LaTeX Workshop 的内置 PDF 查看器在定位 PDF 时会优先读取outDir设置。只要outDir正确插件会去build目录里找 PDF 并打开所以大部分情况下内置预览是免配置的。但如果你之前手动改过latex-workshop.view.pdf.viewer或者使用过某些旧版配置模板插件可能仍然去源目录找 PDF。这种情况的典型表现是编译成功、build目录里也有 PDF但点击预览按钮提示文件不存在。排查思路很简单确认outDir存在确认 PDF 真的在这个目录里然后重新加载窗口。如果还没解决可以把 viewer 设置先调整为tab试试排除外部预览器的干扰。4.2 点击 PDF 跳不回源码反向同步失效了Synctex 是 LaTeX 生态里一个很实用的功能在 VSCode 里Ctrl点击可以跳转到 PDF 对应位置在 PDF 里Ctrl点击又能跳回源码。但指定输出目录后反向同步偶尔会失灵。根本原因通常是.synctex.gz没有生成或者它的位置与插件预期不一致。请检查两处编译参数里是否带了-synctex1。如果用的不是 latexmk而是直接调用 xelatex很容易漏掉这个参数。build目录下是否存在main.synctex.gz文件。如果存在插件理论上会自动识别。如果文件存在但同步还是失败可以检查一下.tex文件编码是否为 UTF-8以及路径里是否包含中文。我在实践中发现部分版本的 Synctex 对非 UTF-8 路径的解析很脆弱与其花时间调它不如把项目路径改成纯英文一劳永逸。4.3 辅助文件清理别再把源目录清空了输出目录已经统一到build了源目录干净了但build里的辅助文件还是会越积越多。LaTeX Workshop 提供了清理功能可以自定义清理规则。我目前的清理配置长这样latex-workshop.latex.clean: [ build/*.aux, build/*.log, build/*.toc, build/*.out, build/*.synctex.gz, build/*.fls, build/*.fdb_latexmk ]注意这个列表是针对工作区根目录的 glob 匹配。如果你的 outDir 不是build需要同步修改前缀。每次编译后可以在 LaTeX 侧边栏点击Clean auxiliary files手动清理也可以配合latexmk -c命令安全清理。这里不推荐用latexmk -C因为它会把最终 PDF 也删掉别问我是怎么知道的。5. 从编译失败到日志定位一条完整的排错链路无论配置写得多完美总会有翻车的时候。下面这段是我在一台新电脑上真实经历过的排错过程用的方法你完全可以照搬。5.1 一次真实的故障复现当时我刚换了工作电脑重新安装 TeX Live 2024并把 VSCode 配置文件和以前一样复制过来。结果打开测试工程后一点编译按钮输出面板直接甩给我一行Recipe terminated with fatal error: spawn latexmk ENOENT这句话翻译过来是VSCode 尝试启动latexmk这个进程但系统根本找不到这个可执行文件。换成大白话说遥控器已经按下了但电视机没开机。我当时的第一反应是TeX Live 没装好于是重新运行安装程序折腾了半天无果。最后发现问题出在环境变量上TEX Live 的安装程序已经把路径写进了系统 PATH但 VSCode 是在 PATH 更新之前启动的它根本没来得及刷新环境变量。解决办法出奇简单完全关闭 VSCode 再重新打开。这里我总结一个实用原则在 VSCode 里遇到ENOENT、spawn ... failed这类错误优先怀疑 PATH 和环境变量而不是怀疑配置本身。很多工具链问题都出在程序能启动但命令找不到这个环节。5.2 日志文件应该怎么看当编译失败时你的第一反应不应该是反复点编译按钮而是去看日志。LaTeX Workshop 的输出面板入口在菜单栏视图 → 输出然后在右上角的下拉框里选择LaTeX Workshop。日志里最有价值的是最后几十行通常包含两类信息工具调用过程比如 latexmk 实际执行的命令行是什么。报错的具体位置比如./main.tex:12: Undefined control sequence.这说明main.tex第 12 行有一个宏命令没定义。有些错误是 LaTeX 自身的语法错误VSCode 侧边栏不会显示只有build/main.log里才写得很详细。打开build目录下的.log文件搜索关键字!通常能定位到真正的崩溃点。学会看这两份日志能帮你省下一大半求人问问题的时间。5.3 中文路径导致的玄学报错我见过不少用户用中文用户名创建了自己的 Windows 账户然后把项目文件放在文档里结果编译报错后大喊LaTeX 太垃圾了。实际上这是路径处理的问题。当 latexmk 收到一个包含中文或空格的路径时不同的命令解析方式会产生歧义。比如xelatex对中文路径的兼容性时好时坏。.synctex.gz文件在中文路径下可能无法正常生成。某些宏包在读取文件时对路径中的非 ASCII 字符处理不当。最省心的做法是新建一个纯英文路径的工作区比如C:\tex\paper或~/latex/paper确认无中文、无空格、无特殊符号。这个方法虽然看起来土但确实能避免一大批坑。5.4 多文件项目谁才是根文件当你的论文拆分成多个.tex文件比如main.tex、chapter1.tex、chapter2.texLaTeX Workshop 在编译时需要一个明确的根文件。如果你打开的是chapter1.tex再点编译插件可能会尝试把这个子文件当作独立文档去编译结果当然是一堆未定义引用和报错。两种主流解决办法在工作区设置里指定根文件latex-workshop.latex.rootFile: main.tex在每个子文件头部写魔法注释% !TeX root main.tex我比较推荐第二种方式因为这种代码具有可移植性换个环境不需要重新配置。而且当你在子文件里时LaTeX Workshop 会自动识别魔法注释直接编译正确的根文件非常顺手。6. 我一直在用的几个配置细节顺便给你提个醒到了这一步你的 VsCode LaTeX 环境已经能稳定工作并指定输出目录了。最后分享几个我在实际使用中沉淀下来的习惯它们不一定会让你的编译速度发生质变但会让日常体验舒服很多。第一个是自动清理的开关。如果你希望每次编译完成后顺手把中间产物删掉可以把latex-workshop.latex.autoClean.run设置为onBuilt。这样每次成功构建后插件都会按照你配置的清理规则删除辅助文件。我自己不会开这个开关因为我经常需要查看.log文件调排版但如果你的项目结构很标准、出问题频率低开着确实能让目录非常清爽。第二个是用 XeLaTeX 处理中文。如果你要写中文论文、带中文书签或者用ctex宏包强烈建议把编译工具改成args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, -outdir%OUTDIR%, %DOC% ]改动的地方只有一个把-pdf换成-xelatex其他的保持不变。latexmk 会自动调用 xelatex并且同样能把所有文件输出到build目录。第三个是备份配置。settings.json是你整个 LaTeX 环境的精髓我建议把它单独存一份到自己的代码仓库或云笔记里换新电脑时直接粘贴即可。我在写这篇内容时用的正是那份备份配置从头到尾没踩过一个多余的大坑。最后再提一个细节如果你在配置过程中遇到了某个报错先别急着复制搜索引擎里的标准答案先看一眼实际的报错语句和日志。配置 LaTeX 环境这件事最重要的不是记住某一段 JSON而是理解outDir和-outdir之间的映射关系。搞懂了这一环剩下的不过是锦上添花。
