VS Code + LaTeX 从入门到入坑：手把手教你搭建高效论文写作环境

前言最近·我一直在寻找一个免费、流畅、可离线的 LaTeX 写作方案。Overleaf 虽然方便但一旦文档大了就卡得怀疑人生本地用 Texmaker 或 TeXstudio界面又太复古。直到我发现了VS Code LaTeX Workshop这套组合拳彻底解放了生产力。今天我就把从零开始配置、到解决各种“奇奇怪怪”报错的完整流程分享出来。文章很长但跟着做你也能拥有一个媲美 IDE 的 LaTeX 写作环境。一、环境搭建安装 LaTeX 发行版1.1 选哪个MiKTeX vs TeX Live特性MiKTeXTeX 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按CtrlShiftX进入扩展商店搜索并安装插件作用LaTeX Workshop核心插件提供编译、预览、语法高亮LaTeX Utilities字数统计、辅助工具可选2.2 配置settings.json按CtrlShiftP输入Preferences: Open User Settings (JSON)添加以下配置{// 定义编译工具latex-workshop.latex.tools:[{name:xelatex,command:xelatex,args:[-synctex1,-interactionnonstopmode,-file-line-error,-pdf,%DOCFILE%]},{name:latexmk,command:latexmk,args:[-synctex1,-interactionnonstopmode,-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 编译点击右上角“播放”按钮▶或按快捷键CtrlAltB编译成功后右侧会自动弹出 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 texcountLinux/macOS或重装 TeX Live 勾选该组件如果安装了但仍报错可能是 Perl 环境问题。安装 Strawberry Perl并添加环境变量PERL_BADLANG0可消除区域设置警告。不想折腾直接在 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按CtrlShiftP执行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 体验