写论文的时候第一次在 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 上首选。安装完整版之后几乎不用再手动补包，因为常用宏包都包含在内。
• MiKTeX：Windows 上的历史选项，特色是“缺什么装什么”，编译时自动下载缺失宏包。听起来方便，但在离线环境或网络不稳时会很尴尬，而且自动安装过程偶尔会打断编译。
• MacTeX：本质是 macOS 上的 TeX Live 预打包版，macOS 用户直接选它。

如果你不确定选哪个，我建议：Windows 和 Linux 用户直接上 TeX Live，macOS 用户用 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 里按Ctrl+Shift+P，输入open user settings，选择“打开用户设置 (JSON)”，就能看到自己的配置文件。下面这些参数是核心。

3.2 settings.json 核心参数：tools 与 recipes

LaTeX Workshop 的配置模型就两个关键词：tools和recipes。tools定义“可以执行哪些命令”，recipes定义“按什么顺序执行哪些命令”。理解这个模型，你就能自由定制编译流程。

先看一个适合中文场景的基础配置：

{ "latex-workshop.latex.tools": [ { "name": "latexmk", "command": "latexmk", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "-xelatex", "%DOC%" ] } ], "latex-workshop.latex.recipes": [ { "name": "latexmk-xelatex", "tools": ["latexmk"] } ] }

这段配置我建议第一次配置的人直接抄过去，原因如下：

• -synctex=1开启正反搜索，这个后面会讲。
• -interaction=nonstopmode遇到错误时不要停下来等用户输入，否则 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 支持，而前面配置里的-synctex=1已经为它铺好了路。

在 VS Code 里，默认的实现方式是这样：

• 正向搜索（源码到 PDF）：在.tex文件里按住Ctrl（macOS 上是Cmd）并点击某一行，右侧 PDF 会跳转到对应位置，并高亮显示。
• 反向搜索（PDF 到源码）：在 PDF 查看器里按住Ctrl（macOS 上是Cmd）并点击某个位置，源码会跳到对应行。

如果你发现点击没有反应，先检查-synctex=1是否在编译参数里。另外，有的用户会额外配置自定义快捷键，但新手阶段不需要动这些。默认行为已经足够好用。

4. 实操流程：从新建文件到生成第一份 PDF

4.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 高频问题速查表

下面这些是我在实际使用和帮别人排查时遇到最多的几类问题，直接整理成表格：

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 就不再是“配置地狱”，而是你写作时真正能托付的排版系统了。