VS Code + TeX Live：配置LaTeX编译环境与中文支持实战

在 VS Code 里配置 LaTeX 编译环境，这件事我前前后后帮不少同事和同学折腾过。别小看这一步，装好之后的体验和没装之前的体验完全是两个世界——装好之前，你觉得 VS Code 写 LaTeX 不过是个带高亮的编辑器；装好之后你才会发现，编译、预览、正反相搜能在一个窗口里完成，比在编辑器、PDF 阅读器之间来回切换舒服太多了。这篇文章就按我的实际操作顺序走一遍，从装 LaTeX 发行版到配置 VS Code 插件，再到解决中文支持和各种常见报错。适合两种情况的人看：一种是完全没装过 LaTeX 的新手，另一种是已经装了但被报错折磨到想放弃的老手。

先说结论：VS Code 本身只是编辑器和编译的调度器，真正干活的是一套 LaTeX 发行版。很多人第一步就装错了，装了个不完整的发行版，后面所有问题都从这里来。所以下面的章节我会从发行版选型开始，一步一步把整个环境捋清楚。

1. 环境选型：为什么是 VS Code + TeX Live

写 LaTeX 需要两个层面的东西：编译引擎和编辑器。编译引擎负责把你写的 .tex 源码变成 PDF，编辑器负责让你写源码时不至于瞎眼。很多新手容易把两者混为一谈，结果在编辑器上反复折腾，却忽略了真正影响编译成败的发行版。我建议的顺序是：先把发行版装好，再谈编辑器。

1.1 LaTeX 发行版：TeX Live 还是 MiKTeX

市面主流的 LaTeX 发行版就两个：TeX Live 和 MiKTeX。前者是跨平台方案，Windows、macOS、Linux 都有对应版本；后者主要面向 Windows，特色是按需安装宏包。我身边长期写论文的人，绝大多数最后都固定在 TeX Live 上，原因有几点：

• TeX Live 的宏包非常全，装完之后很少会遇到缺 .sty 文件的情况。MiKTeX 虽然可以自动补包，但补包时需要联网，国内网络环境下偶尔还会卡住或下载超时。
• TeX Live 每年发布一个版本，版本内所有宏包都和当年的 CTAN 快照对齐，宏包之间版本冲突的概率低。
• TeX Live 自带 latexmk 等辅助工具，后面我配置 VS Code 编译链时会用到，MiKTeX 虽然也有，但细节配置上不如 TeX Live 顺手。

因此我用的是 TeX Live，下面的步骤也以 TeX Live 为准。如果你已经装了 MiKTeX，也不一定要换，只要引擎齐全（xelatex、latexmk 都在），后面的 VS Code 配置思路同样适用。

1.2 VS Code 写 LaTeX，到底比 TeXstudio 香在哪

网上关于 LaTeX 编辑器的推荐很多，传统派会推 TeXstudio、TeXmaker，云文档派会推 Overleaf。VS Code 的优势不在“开箱即用”，而在生态统一。

你如果日常要写代码、用 Git 管理文件、同时写 Markdown 和论文，VS Code 一套软件全包了。团队协作时，别人拉下来的仓库里 .tex、.bib、.png 混在一起，只有通用编辑器才能处理得这么自然。此外 VS Code 的插件机制非常成熟，LaTeX Workshop 这个插件的维护活跃度一直很高，功能上已经不输老牌 LaTeX 编辑器。

代价是配置成本。第一次装完 VS Code + LaTeX 插件后，直接编译可能各种报错，因为默认编译链不一定适合你的中文文档。但只要把配置写对一次，之后可以稳定用上几年，我觉得这个初期投入完全值得。

2. LaTeX 发行版安装实操

我以 Windows 安装 TeX Live 2025 为例。macOS 用 MacTeX，Linux 用发行版自带的 texlive-full，核心逻辑一样，后面会单独说明。

2.1 从哪里下载，ISO 还是在线安装

TeX Live 官网提供安装脚本，但国内直接从官网下载速度不稳定，我一般建议大家用镜像站。清华 TUNA、中科大、腾讯云的镜像都有 texlive 目录，下载 ISO 完整版最省心。

ISO 完整版体积大概五六个 GB，包含所有宏包和文档，好处是安装过程完全离线，不用中途下载。缺点是文件大、安装时间长。如果你不想下载十几个 GB 的东西，也可以选择在线安装方式，用安装脚本只装基础版，后面缺什么宏包再补。但对新手来说，我强烈建议直接上完整版，省得后面反复折腾缺包问题。

下载完 ISO 后可以校验一下 SHA256 是否和镜像站给出的值一致，这是防止文件损坏的有效手段。ISO 文件如果校验不过，挂载安装时可能出现莫名其妙的解压失败，到时候排查起来更烦。

2.2 Windows 下安装 TeX Live 的完整过程

拿到 ISO 后，在 Windows 资源管理器里直接双击挂载，然后进入目录运行 install-tl-windows.bat。注意这一步会弹出一个终端界面，不是图形化安装向导，很多人第一次看到会愣住，其实这就是 TeX Live 的安装界面，英文界面，但需要设置的东西不多。

关键设置就几个：

• 安装路径：默认是 C:\texlive\2025。我有两个建议：一是不要放在系统盘根目录以外的中文或带空格的路径下，比如 D:\我的文档\texlive 这种路径容易引发老宏包兼容问题；二是如果你有 D 盘，可以改成 D:\texlive\2025，这样重装系统也不会丢。
• 安装方案（Scheme）：完整版默认是 full scheme，保持默认即可。安装会持续 30 到 60 分钟，取决于硬盘速度。
• 安装完成后脚本会自动把 D:\texlive\2025\bin\windows 加入系统 PATH，但当前已经打开的终端窗口不会自动生效，需要重开一个终端，或者重启 VS Code。

装完后验证是否成功，在命令行里分别执行：

bash复制latex --version
xelatex --version
latexmk --version

三条命令都能输出版本信息，说明发行版本体没问题。如果提示“不是内部或外部命令”，大概率是 PATH 没生效，重开终端再试。如果重开后还不行，手动检查系统环境变量里是否有 texlive\2025\bin\windows。

2.3 macOS 和 Linux 的一行版说明

macOS 直接下载 MacTeX.pkg 安装包，安装完即可在终端使用 xelatex。Linux 用户最省事的办法是用系统包管理器装完整版：

bash复制sudo apt install texlive-full

Ubuntu、Debian 系的仓库里 texlive-full 已经带了 xelatex、latexmk 和常用宏包，基本够用。唯一要注意的是，部分 Linux 发行版默认不带中文字体，后面编译中文文档时需要额外安装 fonts-noto-cjk。

3. VS Code 侧的准备与插件安装

发行版装好了，下面就在 VS Code 里搭“控制台”。

3.1 VS Code 本体安装的两个小建议

VS Code 安装包从官网下载就行，Windows 上有 User Installer 和 System Installer 两个版本，建议选 User Installer，不用管理员权限，升级也方便。安装过程中有个选项是“添加到 PATH”，建议勾上，后面在终端里直接敲 code 就能打开编辑器，配合命令行效率很高。

第一次打开 VS Code 后，界面默认是英文。不用急着装中文语言包，其实对使用影响不大，LaTeX 相关的报错信息无论什么语言界面都是英文的。如果你实在看不惯英文界面，装个“Chinese (Simplified) Language Pack for VS Code”即可，这只是一个语言包，不影响任何 LaTeX 配置。

3.2 必装插件：LaTeX Workshop 和其他两个辅助

VS Code 里写 LaTeX，核心插件只有一个：LaTeX Workshop。这个插件承担了编译、预览、错误解析、正反相搜等全部功能。另外两个我推荐的辅助插件是：

• LaTeX Utilities：提供一些增强功能，比如 \begin{} 环境补全、章节折叠、引用统计等。
• LaTeX language support：提供更好的语法高亮，和 LaTeX Workshop 配合使用体验更好。

装完这三个插件后，建议重启一次 VS Code，让插件彻底加载。然后在资源管理器里新建一个文件夹，比如 latex-test，在里面新建 test.tex 文件，内容先用最简单的非中文测试：

latex复制\documentclass{article}
\begin{document}
Hello, LaTeX!
\end{document}

此时 LaTeX Workshop 已经会在编辑器的右上角、左侧面板里提供编译按钮。点一下“Build LaTeX project”，如果一切顺利，侧边栏会生成 test.pdf，并且可以直接在 VS Code 里预览。不过这一步很多人在中文文档上会直接失败，因为默认编译链是 pdflatex，对中文的支持非常差，所以我们接下来要改配置。

4. 编译链配置：settings.json 的关键解密

LaTeX Workshop 的配置集中在 VS Code 的 settings.json 里。你可以用快捷键 Ctrl+Shift+P，输入 settings 打开 Preferences: Open User Settings (JSON)，编辑这个文件。

4.1 先理解 tools 和 recipes 这两个概念

LaTeX Workshop 的配置设计里有两个核心概念：tools（工具）和 recipes（配方）。

• tools 定义的是“具体执行什么命令”，比如调用 xelatex 编译一次、调用 latexmk 编译一次。
• recipes 定义的是“按什么顺序调用哪些 tool”，比如先跑一次 xelatex，再跑一次 xelatex，这就是一个配方。

你可以把 tools 想象成厨具，recipes 想象成菜谱。菜谱里写“先热锅，再下菜”，对应编译里就是“先跑一遍 xelatex 生成辅助文件，再跑一遍 xelatex 解析交叉引用”。

LaTeX Workshop 默认已经内置了 pdflatex、xelatex、latexmk 等工具和几个配方。但你用默认配方去编译中文文档，大概率会遇到“Package ctex Error: CTeX fontset fandol' is unavailable”或者直接乱码。原因是默认引擎没有走 xelatex` 路线，而现代中文 LaTeX 文档几乎都依赖 XeLaTeX 引擎。

4.2 我反复使用的一套完整配置

下面这套配置我用了挺长时间，覆盖了日常写论文的所有场景，直接复制到 settings.json 里就能用：

json复制{
  "latex-workshop.latex.tools": [
    {
      "name": "xelatexmk",
      "command": "latexmk",
      "args": [
        "-xelatex",
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
      ],
      "env": {}
    },
    {
      "name": "xelatex",
      "command": "xelatex",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
      ]
    },
    {
      "name": "pdflatex",
      "command": "pdflatex",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk (xelatex)",
      "tools": ["xelatexmk"]
    },
    {
      "name": "xelatex 编译两遍",
      "tools": ["xelatex", "xelatex"]
    },
    {
      "name": "pdflatex 编译",
      "tools": ["pdflatex"]
    }
  ],
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.clean.fileTypes": [
    "*.aux",
    "*.bbl",
    "*.blg",
    "*.fls",
    "*.out",
    "*.fdb_latexmk",
    "*.synctex.gz",
    "*.toc",
    "*.log"
  ],
  "latex-workshop.latex.autoClean.run": "onBuilt"
}

逐个解释一下关键参数。

args 里的 %DOC% 是 LaTeX Workshop 的变量，代表当前的主 TeX 文件。-xelatex 让 latexmk 使用 XeLaTeX 引擎。-synctex=1 开启 SyncTeX 同步数据，这是编辑器和 PDF 之间正反相搜的基础。-interaction=nonstopmode 表示遇到错误不暂停等待输入，避免编译时卡在交互界面。-file-line-error 让报错信息带上文件和行号，VS Code 才能定位到具体行。

latex-workshop.view.pdf.viewer 设为 "tab"，PDF 会在 VS Code 内部的标签页打开。如果你更喜欢在独立窗口里看 PDF，可以改成 "external"，TeX Live 自带的 PDF 阅读器在 Windows 上默认是 SumatraPDF，不过那个需要额外安装。

autoClean.run 设为 "onBuilt"，每次编译后自动删除辅助文件。如果以后有特殊需求想留着 .aux 调试，可以把这项删掉。

4.3 魔法注释：每个文件头部都值得写一行

除了在 settings.json 里指定默认配方，LaTeX Workshop 还支持在 .tex 文件头部写“魔法注释”，用来覆盖全局配置。最常用的是指定编译引擎：

latex复制% !TEX program = xelatex

这句话的意思是：这个文件用 xelatex 编译。它比 settings.json 优先级更高，实际使用起来非常灵活。比如某个文档必须用 pdflatex 编译，你在文件头部写 % !TEX program = pdflatex，插件就不会管全局配方是什么。

对于多文件项目，还有一个更关键的魔法注释：

latex复制% !TEX root = main.tex

写在子文件的头部，指明主文件是 main.tex。这样当你在 chapter1.tex 里按编译快捷键时，插件会知道要先切回主文件再编译，而不是把单个子文件当独立文档编译。这个特性我每次写分章节的论文都会用到，非常实用。

4.4 编译、清理和正向同步的日常用法

配置完成后，日常编译有几种方式：

• 快捷键 Ctrl+Alt+B（Windows / Linux）或 Ctrl+Option+B（macOS），直接按默认配方编译。
• 命令面板 Ctrl+Shift+P 搜索 LaTeX Workshop: Build with recipe，可以手动选择具体配方。
• 侧边栏 TeX 面板里点击 BUILD 图标。

如果编译过程中有错误，VS Code 的“问题”面板（Problems）会列出错误和警告，点击可以直接跳到源码对应行。这个体验很像 IDE 里写代码的报错跳转，比传统 LaTeX 编辑器好用不少。

正向同步：在 .tex 源码里按住 Ctrl 点击某一行，PDF 会跳转到对应位置。反向同步：在 PDF 预览界面里按住 Ctrl 点击某处，编辑器会跳回源码对应行。两者都依赖 -synctex=1，所以我在配置里特意加了这个参数。

5. 中文支持与字体设置实战

中文支持是新手最常卡住的地方。很多时候英文文档编得好好的，一换成中文就各种报错或者方块字。实际上，只要抓住两个核心：编译引擎用 XeLaTeX，宏包用 ctex，90% 的问题都能解决。

5.1 XeLaTeX 和 ctex 宏包为什么是标配

传统的 pdflatex 引擎在处理 UTF-8 编码的中文时，需要额外的 CJK 宏包，而且字体配置非常麻烦。xelatex 引擎原生支持 Unicode，可以直接调用系统字体，配合 ctex 宏包可以自动处理中文排版规范，比如中文缩进、标点压缩、中英文混排间距等。

最小中文文档长这样：

latex复制\documentclass{article}
\usepackage{ctex}
\begin{document}
你好，LaTeX。
\end{document}

用 XeLaTeX 编译，直接就能出正确的中文 PDF。如果你看到满屏方块，先检查两件事：第一，编译引擎是不是 xelatex；第二，系统里有没有中文字体。这两个都满足，一般不会再有问题。

5.2 自定义中文字体和 fontset=none 的用法

ctex 宏包在 Windows 上默认会自动检测系统中文字体，常见的情况是使用“中易宋体”（SimSun）作为正文字体。如果不想用默认字体，可以显式指定字体，示例：

latex复制\documentclass{article}
\usepackage[fontset=none]{ctex}
\setCJKmainfont{SimSun}
\setCJKsansfont{Microsoft YaHei}
\setCJKmonofont{FangSong}
\begin{document}
这是一段自定义字体的中文测试。
\end{document}

这里的 SimSun 是 Windows 的系统字体名。Linux 用户如果没装中文字体，可以先安装 fonts-noto-cjk，然后在 \setCJKmainfont 里使用 Noto Serif CJK SC 之类的字体名。注意字体名必须和系统里的实际字体名完全一致，否则编译时会报找不到字体的错误。想知道系统有哪些中文字体，可以用 fc-list :lang=zh 命令查看。

5.3 源码编码和编辑器换行符的小坑

日常写完中文文档后保存，VS Code 默认使用 UTF-8 编码，这是正确的。但如果项目里用过别的编辑器，比如 Windows 自带记事本的旧版 ANSI 编码保存过，编译时中文可能全部乱码。判断方法很简单：打开 .tex 文件，看 VS Code 右下角显示的是 UTF-8 还是其他编码，不是 UTF-8 就通过命令面板执行“Change File Encoding”改回来。

另外一个小细节：.tex 文件的行尾符建议保持默认的 Linux 风格（LF）。虽然 Windows 风格（CRLF）绝大多数情况下也能编译，但遇到一些上古宏包时，CRLF 偶尔会引发奇怪的调试问题。VS Code 右下角可以看到行尾符类型，统一设置成 LF 能省不少心。

6. 常见问题与排查实录

配置环境过程中，我遇到过不少报错，也帮别人排查过不少。下面这几个问题是最常见的，按频率从高到低排。

6.1 编译时提示找不到 latexmk 或 xelatex

这是一个经典的“环境变量失效”问题。TeX Live 安装完成后，PATH 已经写入了，但 VS Code 是安装之前就打开了的，所以它启动时读取到的 PATH 里没有 TeX Live 的路径。解决办法很简单：完全退出 VS Code 再重新打开。注意是“完全退出”，直接关窗口有时候进程还在后台。

如果重启后还是找不到，手动在终端里输入 where latexmk，看能不能定位到。如果能定位，说明系统 PATH 没问题，可能是 VS Code 的继承问题，重启电脑一般能解决。如果终端里也找不到，那就回到第 2 节手动检查环境变量。

6.2 首次编译动不动就卡住，甚至提示超时

第一次用 XeLaTeX 编译中文文档时，系统需要扫描和建立字体缓存，这个过程可能长达一两分钟，看起来像卡死了。其实它还在跑，你切到 LaTeX Workshop 的日志面板就能看到进度，耐心等一会儿就好。之后的编译就不会这么慢了。

另外，如果编译中途弹出交互界面等待输入，多半是没有加 -interaction=nonstopmode 参数。我上面那套配置里已经加了，新配置的读者直接复制就行。

6.3 用 pdflatex 编译中文导致的乱码或报错

这个我刚开始写中文文档的时候踩过。当时以为 LaTeX 能直接处理中文，用默认配方编译，结果满屏乱码。原因很简单：默认配方是 pdflatex，而这个老牌引擎需要额外的 CJK 支持，和现代工作流不搭。

解决办法：文件头部加魔法注释 % !TEX program = xelatex，或者在 recipes 里把第一个配方换成 latexmk (xelatex)。这样每次编译自动走 XeLaTeX 路线。

6.4 编译成功但 PDF 预览打不开或不同步

如果 PDF 生成了，但 VS Code 预览打不开，先确认 latex-workshop.view.pdf.viewer 设置是否是 "tab"。想在外部阅读器打开，需要额外安装 SumatraPDF，并且把路径配置进插件，具体配置项是 latex-workshop.view.pdf.external.viewer.command，这里不展开，因为内置 tab 预览已经够用。

SyncTeX 不工作的话，检查两点：编译参数里有没有 -synctex=1；PDF 是不是最新编译生成的。有时候你改了源码没编译，直接点 PDF 里的旧内容，自然跳转不到新位置。

6.5 缺宏包报错：LaTeX Error: File `xxx.sty' not found

TeX Live 完整版很少出现这种情况。如果出现，说明当前文档依赖了某个宏包，但发行版里没有。优先确认你的 TeX Live 是不是完整版；如果确实是完整版，那可能是宏包名拼写错误。如果是在线安装的基础版，需要回安装脚本补装，或者用 tlmgr install 宏包名 手动安装。

6.6 常见问题速查表

7. 从折腾到顺手：几个值得养成的习惯

环境配好只是开始，真正提高效率的是使用习惯。下面是我用 VS Code 写 LaTeX 这几年沉淀下来的几个工作流建议。

7.1 给新手的极简配置模板

如果你不想用我上面那一大段配置，也可以从最简单的方案开始：只装 LaTeX Workshop 插件，然后在每个 .tex 文件头部写魔法注释：

latex复制% !TEX program = xelatex

这样 LaTeX Workshop 会根据魔法注释自动选择引擎，不需要手动改 settings.json。先跑通最小示例，再逐步加自定义配置。对新手来说，这种方式最不容易出错。

7.2 分章节写作时用主文件 + 子文件结构

论文写长了，一个 .tex 文件几十上百页，滚动查找都很痛苦。我习惯用主文件 + 子文件的方式组织：

• main.tex：导言区（宏包、标题、目录设置），然后用 \include{chapter1}、\include{chapter2} 包含各章。
• chapter1.tex、chapter2.tex：各章正文，头部写 % !TEX root = main.tex。

这样每章一个文件，编辑体验清爽，编译时 latexmk 也会自动识别主文件。配合 VS Code 的折叠功能和章节导航，浏览长文档比传统编辑器舒服很多。

7.3 用 Git 管理 LaTeX 项目，但要记得忽略辅助文件

LaTeX 项目本质上是纯文本，非常适合用 Git 管理。但编译会生成一堆 .aux、.log、.out、.toc 文件，这些不需要进版本库。我一般在项目根目录放一个 .gitignore，内容至少包含：

gitignore复制*.aux
*.log
*.out
*.toc
*.fls
*.fdb_latexmk
*.synctex.gz
*.bbl
*.blg
*.nav
*.snm

这样别人 clone 下来后，只需要源码就能重新编译，不会因为提交了过时的辅助文件而产生奇奇怪怪的冲突。

7.4 和 Overleaf 配合使用时的一个小技巧

很多团队最终投稿用 Overleaf 协作，本地用 VS Code 写可以保留个人偏好。我的做法是：本地用 Git 管理，Overleaf 项目通过 GitHub 同步。具体连接方式 Overleaf 官方有文档，这里不展开。重点提醒一下：本地和 Overleaf 的宏包版本可能有差异，投稿前一定在 Overleaf 上完整编译一遍，确认没问题再排版。曾经有同事在本地用最新的宏包没问题，传到 Overleaf 因为宏包版本差异导致表格错位，折腾了半个晚上。

7.5 顺手回答一个高频疑问：LaTeX 的“右斜线”怎么打

搜索热词里这个查的人特别多。LaTeX 命令的开头是反斜杠 \，不是右斜杠 /。键盘上通常在回车键的上方，和 / 相邻。中文输入法状态下按这个键也能直接打出来，不用切换到英文输入法。如果你在 LaTeX 里输入 /，那就是单纯的斜杠字符，不会触发任何命令。很多教程截图里那些 \documentclass、\begin 开头的代码，前面那个字符就是反斜杠。

这个环境我从课程报告一直用到毕业论文，中途换过电脑、换过发行版版本，但 VS Code + TeX Live 这个组合一直没变。回过头看，我最推荐的组合其实很简单：完整版 TeX Live + LaTeX Workshop 插件 + 一份不走偏的编译配置，再配合魔法注释和 Git 管理，写 LaTeX 的体验完全不输任何专业编辑器。如果你照着配置过程中遇到本文没提到的报错，不妨先把日志面板里红色部分的完整报错贴出来，多半是宏包缺失或者路径问题，顺着日志排查基本都能解决。