前言
最近·，我一直在寻找一个免费、流畅、可离线的 LaTeX 写作方案。Overleaf 虽然方便，但一旦文档大了就卡得怀疑人生；本地用 Texmaker 或 TeXstudio，界面又太复古。直到我发现了VS Code + LaTeX Workshop这套组合拳，彻底解放了生产力。
今天，我就把从零开始配置、到解决各种“奇奇怪怪”报错的完整流程分享出来。文章很长，但跟着做，你也能拥有一个媲美 IDE 的 LaTeX 写作环境。
一、环境搭建：安装 LaTeX 发行版
1.1 选哪个？MiKTeX vs TeX Live
| 特性 | MiKTeX | TeX Live |
|---|---|---|
| 安装大小 | 约 200 MB（按需下载） | 完整版 4-6 GB |
| 宏包安装 | 编译时自动下载 | 一次性全装 |
| 更新频率 | 持续更新 | 年度大版本 |
| 平台 | Windows 最佳 | 跨平台一致 |
| 适合人群 | 硬盘小、网络好的新手 | 追求稳定、跨平台的用户 |
我的选择：Windows 用户推荐MiKTeX（省空间、自动装宏包），Linux/macOS 推荐TeX Live。我自己用的是 TeX Live 2026，全量安装一劳永逸。
1.2 安装 TeX Live（以 Windows 为例）
- 下载 TeX Live 镜像，运行
install-tl-windows.exe - 选择“安装完整版”（约 5-6 GB，耐心等待半小时）
- 安装完成后，务必勾选“将 TeX Live 添加到系统 PATH”
⚠️巨坑预警：如果忘记勾选 PATH，后面 VS Code 会报
spawn xelatex ENOENT，别慌，后面会教你怎么手动加。
1.3 验证安装
打开命令提示符（cmd），输入：
xelatex--version如果看到类似输出，说明安装成功：
XeTeX 3.141592653-2.6-0.999998 (TeX Live 2026) ...二、VS Code 配置：安装插件
2.1 核心插件
打开 VS Code，按Ctrl+Shift+X进入扩展商店，搜索并安装：
| 插件 | 作用 |
|---|---|
| LaTeX Workshop | 核心插件，提供编译、预览、语法高亮 |
| LaTeX Utilities | 字数统计、辅助工具（可选） |
2.2 配置settings.json
按Ctrl+Shift+P，输入Preferences: Open User Settings (JSON)，添加以下配置：
{// 定义编译工具"latex-workshop.latex.tools":[{"name":"xelatex","command":"xelatex","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","-pdf","%DOCFILE%"]},{"name":"latexmk","command":"latexmk","args":["-synctex=1","-interaction=nonstopmode","-file-line-error","-pdf","-xelatex","%DOCFILE%"]}],// 定义编译配方（按顺序执行）"latex-workshop.latex.recipes":[{"name":"XeLaTeX","tools":["xelatex"]},{"name":"latexmk (XeLaTeX)","tools":["latexmk"]}],// 设置默认配方"latex-workshop.latex.recipe.default":"latexmk (XeLaTeX)",// 保存时自动编译"latex-workshop.latex.autoBuild.run":"onSave",// 使用内置 PDF 预览器"latex-workshop.view.pdf.viewer":"tab"}保存后重启 VS Code。
三、第一个 LaTeX 文档
3.1 创建文件
新建文件，保存为main.tex，输入以下内容：
%!TEX program = xelatex \documentclass[UTF8]{ctexart} \title{我的第一篇论文} \author{龙思吉} \date{\today} \begin{document} \maketitle \section{引言} 这是一个测试，看看中文是否正常显示。 \subsection{子章节} 数学公式：$E = mc^2$。 \end{document}3.2 编译
- 点击右上角“播放”按钮▶
- 或按快捷键
Ctrl+Alt+B - 编译成功后，右侧会自动弹出 PDF 预览
🎉 恭喜！你已经成功跑通第一个 LaTeX 文档！
四、常见报错与解决方案（血泪史）
下面是我在实际使用中踩过的坑，以及解决方法。
4.1spawn xelatex ENOENT
错误现象：编译时报错，提示找不到xelatex。
原因：系统 PATH 里没有 TeX Live 的路径，或者 VS Code 没继承到。
解决方案：
手动添加 PATH：
- 打开“环境变量”设置（搜索“环境变量”）
- 在“系统变量”中找到
Path，编辑 - 新建一条：
C:\texlive\2026\bin\windows（根据你的安装路径和年份调整） - 确定保存，重启电脑
在 VS Code 中强制指定路径：
"latex-workshop.latex.tools":[{"name":"xelatex","command":"C:/texlive/2026/bin/windows/xelatex.exe",...}]如果系统终端能用但 VS Code 不行：取消勾选
terminal.integrated.inheritEnv设置，或调整 PATH 顺序，将 TeX Live 路径上移到最顶部。
4.2TeXCount failed错误
错误现象：VS Code 底部状态栏提示“TeXCount failed”。
原因：LaTeX Utilities插件需要texcount工具来统计字数，但系统找不到它。
解决方案：
- 检查是否安装：终端输入
texcount --version - 如果没有：
- MiKTeX 用户：在 MiKTeX Console 中搜索
texcount并安装 - TeX Live 用户：
sudo tlmgr install texcount（Linux/macOS）或重装 TeX Live 勾选该组件
- MiKTeX 用户：在 MiKTeX Console 中搜索
- 如果安装了但仍报错：可能是 Perl 环境问题。安装 Strawberry Perl，并添加环境变量
PERL_BADLANG=0可消除区域设置警告。 - 不想折腾：直接在 VS Code 设置中搜索
countWord，取消勾选LaTeX-Utilities › Count Word: Enable，关闭字数统计功能。
4.3Cannot find mlint错误
错误现象：打开.m文件时提示找不到mlint。
原因：MATLAB 插件需要mlint.exe进行代码检查，但路径配置不对。如果你电脑上有多个 MATLAB 版本，更容易出现此问题。
解决方案：
- 找到
mlint.exe的位置（通常在MATLAB\R2024a\bin\win64\mlint.exe） - 在 VS Code 的
settings.json中添加："matlab.mlintpath":"D:/MATLAB/R2024a/bin/win64/mlint.exe" - 如果你想切换版本，使用命令面板
MATLAB: Select MATLAB选择不同的 MATLAB 安装。
4.4PrinceXML is required错误
错误现象：用 Markdown 导出 PDF 时提示需要安装 Prince。
原因：Markdown Preview Enhanced 插件默认调用 Prince 引擎将 HTML 转换为 PDF。
解决方案：
- 下载安装 Prince
- 安装后，将 Prince 的
bin目录添加到系统 PATH（如C:\Program Files (x86)\Prince\engine\bin） - 重启 VS Code，再次导出即可。
💡 替代方案：你也可以用 Chrome 浏览器打开预览页面，然后“打印→另存为 PDF”，不需要安装 Prince。
4.5 中文文档编译报错
错误现象：中文显示为乱码或报错Undefined control sequence。
解决方案：使用ctex宏包，并用 XeLaTeX 编译。
\documentclass[UTF8]{ctexart} % 或者 \usepackage{ctex}确保文件保存为UTF-8 编码（VS Code 右下角可以查看/修改）。
五、进阶技巧：让写作更高效
5.1 正向/反向搜索
- 正向搜索（从代码跳转到 PDF）：在
.tex文件中按住Ctrl并点击某处，右侧 PDF 会自动跳转 - 反向搜索（从 PDF 跳回代码）：在 PDF 预览中按住
Ctrl并点击，光标会跳回.tex对应行
5.2 使用latexmk自动处理参考文献
如果你的文档有.bib文件，推荐使用latexmk配方，它会自动运行xelatex→biber→xelatex× 2，省去手动多次编译的麻烦。
5.3 代码片段
安装LaTeX Workshop后，输入begin按 Tab 会自动补全\begin{}...\end{}，输入fig会生成图片环境模板，非常方便。
5.4 实时字数统计
如果你解决了texcount的问题，状态栏会实时显示当前文档的字数。否则可以手动运行texcount main.tex来统计。
六、从 Overleaf 迁移到本地
方法一：下载 ZIP 包
- 在 Overleaf 项目页面点击Menu → Source → Download as ZIP
- 解压后用 VS Code 打开文件夹
- 配置好编译器，直接编译
方法二：使用 Git 同步（推荐）
- 在 Overleaf 账户设置中生成Git Token
- 安装 VS Code 插件Overleaf Connect
- 按
Ctrl+Shift+P执行Overleaf Connect: Clone Overleaf Project，输入 Token 和项目 ID - 本地修改后自动同步到云端
七、总结
经过上述配置，你的 VS Code 已经变成一个强大的 LaTeX 编辑器。总结一下关键步骤：
- 安装 LaTeX 发行版（TeX Live 或 MiKTeX）
- 安装 VS Code 插件
LaTeX Workshop - 配置
settings.json，指定xelatex工具和编译配方 - 解决常见报错：PATH 问题、
texcount、mlint、Prince等 - 开始写作：享受流畅的离线 LaTeX 体验！
