拖了好几年，我终于把写毕业论文的战场从 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_latexmk | latexmk 记录的文件依赖关系，用于判断下次编译是否需要增量更新 |
这些文件不是可有可无的垃圾。交叉引用之所以需要"编译两遍才能正确显示页码"，就是因为第一遍.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 里按下Ctrl+Shift+P，输入"Preferences: Open Workspace Settings"，打开工作区设置。如果你希望所有 LaTeX 项目都使用这套配置，就打开用户设置。然后把下面的内容放进去：
{ "latex-workshop.latex.tools": [ { "name": "latexmk", "command": "latexmk", "args": [ "-synctex=1", "-interaction=nonstopmode", "-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" }改完之后别忘记重新加载窗口：Ctrl+Shift+P→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宏包，对中文支持更友好。
-synctex=1会生成.synctex.gz文件，这个文件是实现 VSCode 和 PDF 双向同步跳转的关键。-interaction=nonstopmode的意思是遇到错误不要停下等待用户交互，直接以非交互模式推进，这样 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 就行的，很多修改需要重载窗口才能被插件读取。完成上述步骤后，我建议按这个顺序验证：
Ctrl+Shift+P→Reload Window。- 打开
main.tex，按下Ctrl+S。 - 观察底部输出面板中的编译日志。
- 确认
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没有生成，或者它的位置与插件预期不一致。请检查两处：
- 编译参数里是否带了
-synctex=1。如果用的不是 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.tex，LaTeX 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": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-xelatex", "-outdir=%OUTDIR%", "%DOC%" ]改动的地方只有一个：把-pdf换成-xelatex，其他的保持不变。latexmk 会自动调用 xelatex，并且同样能把所有文件输出到build目录。
第三个是备份配置。settings.json是你整个 LaTeX 环境的精髓，我建议把它单独存一份到自己的代码仓库或云笔记里，换新电脑时直接粘贴即可。我在写这篇内容时用的正是那份备份配置，从头到尾没踩过一个多余的大坑。
最后再提一个细节：如果你在配置过程中遇到了某个报错，先别急着复制搜索引擎里的"标准答案"，先看一眼实际的报错语句和日志。配置 LaTeX 环境这件事，最重要的不是记住某一段 JSON，而是理解outDir和-outdir之间的映射关系。搞懂了这一环，剩下的不过是锦上添花。
