1. 为什么是 VS Code LaTeX编辑器的选择逻辑先说说我自己的经历。本科写毕业论文那会儿我用的还是 Word格式调了一整天目录自动生成之后页码全乱了图注和表注的编号手动改了十几处最后交上去导师一句参考文献格式不对我又挨个改了两个小时。后来读研接触了 LaTeX头一个星期痛不欲生但熟悉之后,再也没回去碰过 Word原因很简单LaTeX 把排版这件事彻底自动化了你只管写内容格式交给编译引擎。但 LaTeX 有一个非常现实的问题编辑器。很多人第一反应是用 TeXworksTeX Live 自带或者 TeXstudio我用过一段时间那时候的感觉是能用但憋屈。直到有一天实验室的同事推荐我用 VS Code 试试我才发现原来 LaTeX 写作也可以有现代编辑器的体验。VS Code 本身是微软开源的一个代码编辑器它内置了终端、 Git 管理、插件体系配合 LaTeX Workshop 插件后LaTeX 的编译、预览、错误定位全部可以在一个窗口里完成。更重要的是它不像 TeXstudio 那样重装完只有几百MB启动速度快界面也干净。这篇文章不是什么高深教程是我自己从零开始搭环境、写论文、踩坑、排查问题的一套完整记录。适合三类人还在用 Word 写的论文的本科生、刚进实验室被导师要求用 LaTeX 的研究生、以及装了 VS Code 和 TeX Live 但一直没跑通编译的人。我会从软件安装讲起一直讲到论文实战里的公式、插图、表格、参考文献和常见报错排查。先说结论VS Code LaTeX Workshop TeX Live latexmk这套组合是目前我用过的所有本地 LaTeX 写作方案里最舒服的没有之一。2. Windows 下 LaTeX 发行版选型与安装TeX Live 还是 MiKTeXLaTeX 本质上是一套排版系统你需要先装一个发行版它包含编译引擎、宏包、字体和文档等。Windows 上主流的两个发行版是 TeX Live 和 MiKTeX很多人纠结选哪个我这里直接给结论。2.1 TeX Live 和 MiKTeX 的取舍TeX Live是国际 TeX 用户组维护的跨平台发行版一年发布一个大版本默认安装包含几乎所有常用宏包几百个。好处是离线可用、版本统一、编译稳定坏处是完整安装体积很大大约 7-8 GB基本安装小一点但需要自己挑选宏包集合。MiKTeX是 Windows 上老牌的发行版它的特点是按需自动安装宏包。你写完\usepackage{xxx}之后编译时如果缺包它会弹窗问你是否在线安装。这对新手很友好省去了一开始就下载所有宏包的等待时间。但缺点也很明显每次缺包都要联网下载如果论文导师给的模板比较冷门有可能缺一堆包另外不同机器上版本不一致容易出现我这能编、你那编不了的情况。我自己的选择是TeX Live 完整安装。原因很简单论文写作和写代码不一样代码项目可以在不同机器上同步依赖论文宏包没那么容易维护。我踩过一次坑——实验室的机器装的是 MiKTeX我写的一篇论文在 TeX Live 上编译正常迁移过去之后报了一个tcolorbox宏包版本太老的问题最后升级了整个 MiKTeX 才算解决。从那以后我就统一用 TeX Live 了。2.2 TeX Live 安装的完整步骤前往 TeX Live 官网tug.org/texlive下载install-tl-windows.exe或者通过国内镜像站比如清华 TUNA 镜像下载 ISO 镜像。国内推荐用镜像速度快很多。运行安装程序一路点 Next到选择安装方案这一步建议选择『完整方案scheme-full』。虽然体积大但省心之后不会再因为缺包折腾。安装时间取决于网络和硬盘速度一般需要 20-60 分钟。耐心等它跑完。安装完成后打开 CMD 或 PowerShell输入latex --version看到版本信息就说明装好了。latex --version # 输出类似pdfTeX 3.141592653-2.6-1.40.25 (TeX Live 2023)2.3 VS Code 安装与必要插件VS Code 的安装基本没什么坑官网下载安装包默认选项安装即可。装完以后第一件事是安装中文语言包如果不习惯英文界面但不装也不影响使用因为我建议后面所有配置项都用英文避免编码问题。核心插件只有两个LaTeX WorkshopLaTeX 编译、预览、清理、检查的一体化插件核心中的核心。LaTeX Utilities帮你查看文档结构、计数单词数、跳转到对应引用的辅助插件可选但推荐。安装完 LaTeX Workshop 后先别急着写代码打开设置Ctrl,搜索latex-workshop.latex.recipe确认默认编译方案里有latexmk。这一步是后面所有顺利编译的前提。我不建议用别人分享的一整个 settings.json 直接覆盖因为你不知道对方的 TeX 版本、系统路径、工作区结构和你是否一致。后面第 3 节我会列出我实际在用的配置并逐项解释为什么这么配。3. 核心配置解析settings.json 里每一项的用途LaTeX Workshop 的默认配置其实已经能跑通文档编译但真正好用的配置需要自己打磨。我把我目前这份配置贴出来然后逐项说明理由。你可以直接复制放到自己的 settings.json 里但建议至少读一遍注释知道每一项是干嘛的。3.1 我的推荐配置{ // 编译方案latexmk 为主pdflatex 备用 latex-workshop.latex.recipes: [ { name: latexmk, tools: [latexmk] }, { name: pdflatex, tools: [pdflatex] } ], // 编译工具的真实执行命令 latex-workshop.latex.tools: [ { name: latexmk, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, -outdir%OUTDIR%, %DOC% ], env: {} }, { name: pdflatex, command: pdflatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ], // 编译完成之后自动清理辅助文件 latex-workshop.latex.clean.subfolder.enabled: true, latex-workshop.latex.autoClean.run: onBuilt, // 正向同步从代码跳转到 PDF 对应位置 latex-workshop.view.pdf.viewer: tab, latex-workshop.synctex.afterBuild.enabled: true, // 文件保存时自动编译关闭弹窗 latex-workshop.latex.autoBuild.run: onSave, latex-workshop.message.update.show: false, latex-workshop.latex.autoBuild.interrupt: true, // 将 LaTeX 文件当作普通文本进行拼写检查 files.associations: { *.tex: latex } }3.2 关键参数的解释latexmk 是什么这是 Perl 写的一个自动化编译工具它会自动判断需要运行几次编译和索引。比如你用了 BibTeX它会按 pdflatex → bibtex → pdflatex → pdflatex 的顺序自动跑完你完全不用手动控制编译顺序。这也是我在 2.1 里选 TeX Live 的原因之一——TeX Live 自带 latexmk开箱即用。-synctex1和-file-line-error这两个参数一起用VS Code 才能在编译报错时帮你直接从错误日志跳转到源文件报错行。没有这个你看到一条报错消息得自己去代码里找是哪一行很痛苦。-interactionnonstopmode表示编译过程中遇到错误不暂停等待输入。这个参数对论文写作非常重要——你写了几百行内容中间某一行有个小错误如果编译停下来等你输入你还没法在 VS Code 里输入整个编译会卡住。设置成 nonstopmode 后它会把所有错误列出来然后尽量继续编译最后统一报告。autoBuild.run: onSave是保存后自动编译。实测下来比onFileChange更合理后者会在你还在打字的时候频繁触发编译电脑风扇呼呼转极其烦人。autoClean.run: onBuilt是编译完之后自动清理中间文件.aux、.log、.synctex.gz 等。这些文件对最终 PDF 没用但会在你项目目录里堆一大堆。开启后项目目录干净很多。3.3 为什么我不推荐直接抄网上的配置网上很多教程会在配置里加latex-workshop.latex.recipe: [latexmk]这种写法但这是旧版插件的字段方式新版已经改成了recipes数组的形式。如果你用的新插件却抄了旧配置轻则配置无效重则编译方案直接崩掉。我的建议是以官方文档为准确认插件的版本号再对照我的配置自行调整。插件的版本可以在 VS Code 的扩展面板里看到如果你用的版本比我新个别字段可能已经变更但核心项基本稳定。4. 从零写第一篇LaTeX 文档骨架与编译流程环境和配置都就绪了接下来最重要的是写一篇完整可编译的文档把整个流程跑通。我见过不少人配好环境之后还去纠结该先学什么语法其实没必要直接拿论文模板开写就好。4.1 最简文档结构新建一个文件夹比如thesis在里面新建main.tex先写下面的内容\documentclass[12pt, a4paper]{article} % ---------- 导言区 ---------- \usepackage[utf8]{inputenc} \usepackage{amsmath, amssymb} \usepackage{graphicx} \usepackage{float} \usepackage{caption} \usepackage{subcaption} \usepackage{booktabs} \usepackage[hidelinks]{hyperref} \title{基于深度学习的图像分类方法研究} \author{张三 \thanks{某某大学计算机学院}} \date{\today} % ---------- 正文区 ---------- \begin{document} \maketitle \tableofcontents \newpage \section{引言} \label{sec:intro} 这是第一篇 LaTeX 文档。 \section{相关工作} \label{sec:related} 这一节介绍现有方法。 \section{方法} \label{sec:method} \section{实验} \label{sec:experiment} \section{结论} \label{sec:conclusion} \end{document}保存之后按CtrlS触发自动编译。如果配置正确右下角会依次显示 Build LaTeX project → Success。然后左侧边栏会出现 PDF 预览的图标点进去就能看到渲染效果。4.2 编译成功后的第一件事检查目录跳转编译成功后按住Ctrl点击 PDF 预览中的目录条目能跳转到对应章节。反过来在 main.tex 的某个章节名上按CtrlAltJPDF 预览会同步跳到那个位置。这两个方向的双向跳转是 VS Code 写 LaTeX 最爽的功能没有之一。如果发现跳转不灵先检查是不是用了synctex1其次是看有没有安装 SumatraPDF 之类的 PDF 阅读器做关联VS Code 内置 viewer 也支持但体验略逊一筹。4.3 中文字体的处理如果你直接拿上面的模板编译中文内容大概率会报错或者出现乱码因为在最早的 LaTeX 方案里中文支持需要额外配置。现在最简单的办法是用ctexart文档类替代article\documentclass[12pt, a4paper]{ctexart}ctexart是中文社区维护的文档类它自动处理了中文字体、标点压缩、段落缩进等问题。写中文论文推荐直接用它省去了一堆xeCJK之类的手动配置。注意使用ctexart时编译引擎必须是XeLaTeX而不是默认的 pdflatex。在 LaTeX Workshop 的 recipes 里你需要确保 latexmk 传参时带上-xelatex或者在文档开头写一行注释魔法注释% !TEX program xelatex。我在实际使用中发现在 VS Code 里最稳妥的方式是给 main.tex 开头加一行% !TEX program xelatex这个 magic comment 会强制 latexmk 使用 xelatex 引擎避免在电脑上换了项目之后忘改配置。如果你用ctexart却用 pdflatex 编译通常会报类似 Not able to load 宋体 的字体错误。4.4 项目的拆分主文件与子文件论文长了以后把所有内容堆在一个 main.tex 里翻起来和编辑起来都很痛苦。我习惯按章节拆成多个文件比如chapters/introduction.tex、chapters/method.tex然后在主文件里用\input{}或\include{}引入。\include{chapters/introduction} \include{chapters/related} \include{chapters/method} \include{chapters/experiment} \include{chapters/conclusion}\input和\include的区别在于\include会在每个子文件前后自动分页适合章节独立的情况而\input是直接把文件内容粘贴进来适合节或者段落级别的拆分。写论文章节用\include更合适因为每章从新的一页开始通常是论文的硬性要求。5. 论文写作刚需公式、插图、表格与参考文献实战这几样是论文里最常处理的内容也是 LaTeX 相比 Word 优势最明显的地方。我逐个讲。5.1 数学公式从行内到多行对齐公式分两种行内公式和行间公式。行内公式写作$...$比如$E mc^2$。行间公式写作\[...\]或者在 equation 环境里\begin{equation} \label{eq:loss} L -\sum_{i1}^{N} y_i \log p_i \end{equation}多行对齐的公式用align环境对齐位置用标记\begin{align} f(x) (x a)^2 \\ x^2 2ax a^2 \end{align}这里有一个坑如果你在equation环境里写多行内容会直接报错因为 equation 环境只支持单行公式。多行必须用align、gather、multline等环境。我刚开始学时经常搞混。LaTeX 数学符号很多不用背。我平时的习惯是网上搜LaTeX 数学符号大全找一张速查表存下来用到哪个查哪个写多了自然就熟了。也有专门的 VS Code 插件比如LaTeX Sympy Calculator能可视化插入符号但个人认为查表更快。5.2 插图路径、浮动体与双栏排列插图用graphicx宏包\begin{figure}[H] \centering \includegraphics[width0.8\textwidth]{figures/overview.png} \caption{系统总体架构图} \label{fig:overview} \end{figure}这里面有几个点要注意[H]大写 H强制把图片放在当前位置。默认的[htbp]会让 LaTeX 自动决定图片位置可能出现在和你预期不符的地方。但注意有些模板不允许使用[H]因为会破坏排版这时候要遵循模板的规范。figures/是相对路径我建议把论文里所有图片放在figures文件夹里保持项目整洁。图片格式建议优先使用 PDF 或 EPS 矢量图导出为 PNG 也可以分辨率要高300dpi 以上但别用 JPG文字会虚。如果你需要并排显示多张子图用subcaption宏包里的subfigure环境\begin{figure}[H] \centering \begin{subfigure}[b]{0.45\textwidth} \includegraphics[width\textwidth]{figures/result1.png} \caption{方法 A 的结果} \end{subfigure} \hfill \begin{subfigure}[b]{0.45\textwidth} \includegraphics[width\textwidth]{figures/result2.png} \caption{方法 B 的结果} \end{subfigure} \caption{对比实验结果} \label{fig:compare} \end{figure}5.3 表格三线表与自动换行学术论文里最常用的表格风格是三线表booktabs 宏包\begin{table}[H] \centering \caption{不同方法的准确率对比} \label{tab:accuracy} \begin{tabular}{lcc} \toprule 方法 准确率 F1 分数 \\ \midrule BaseLine A 85.3\% 83.1\% \\ BaseLine B 87.9\% 86.0\% \\ Our Method 92.4\% 91.2\% \\ \bottomrule \end{tabular} \end{table}很多人会卡在表格内容太长自动换行这个问题上。默认的tabular环境是不会自动换行的要么手动用\parbox或p{宽度}列类型限制宽度\begin{tabular}{p{3cm}p{6cm}}p{6cm}表示这一列宽度固定为 6 厘米内容超出会自动换行。如果你想要表格自适应页面宽度可以考虑tabularx宏包\begin{tabularx}{\textwidth}{lX} 方法说明 详细描述内容很长很长 \\ \end{tabularx}其中X列会自动填充剩余宽度。另外一个我后来才发现的技巧如果表格内容是从 Excel 或 Python 导出的数据太多手动在 LaTeX 里敲表格非常容易出错。我的做法是用 Python 的pandas.to_latex()直接生成 LaTeX 表格代码再粘贴进文档。生成结果自动带对齐符号和换行比自己手敲省事太多。5.4 参考文献BibTeX 自动编号与会话引用参考文献是论文写作中的一大痛点。LaTeX 里的标准做法是用 BibTeX。首先在项目里建一个references.bib文件整理论文条目article{kingma2015adam, title{Adam: A Method for Stochastic Optimization}, author{Kingma, Diederik P and Ba, Jimmy}, journal{ICLR}, year{2015} } inproceedings{he2016deep, title{Deep Residual Learning for Image Recognition}, author{He, Kaiming and Zhang, Xiangyu and Ren, Shaoqing and Sun, Jian}, booktitle{CVPR}, pages{770--778}, year{2016} }然后在正文引用的地方写作\cite{kingma2015adam}。编译时latexmk 会自动处理 BibTeX 的流程。如果参考文献没显示出来通常是因为这样几个原因忘记用\bibliographystyle{plain}和\bibliography{references}声明参考样式和 bib 文件全文没有任何\cite{}引用BibTeX 默认不会把未引用的条目加入参考文献表引用了但 BibTeX 没编译需要多次编译。如果你需要一次引用多篇参考文献比如[12-14]这种连续引用可以写作\cite{kingma2015adam, he2016deep}或者用\cite{a, b}输出为[2, 6]然后修改样式为\cite{kingma2015adam}--\cite{he2016deep}这种强制方式。更常用的是用natbib宏包\usepackage[numbers, sortcompress]{natbib}sortcompress选项会自动把连续的多篇引用压缩成范围形式如[12-14]。这个是写论文时非常实用的一个功能很多期刊模板本身就用了 natbib。5.5 引用与交叉引用论文的章节、公式、图表之间经常要互相引用。LaTeX 的做法是给目标对象加\label然后在别处用\ref引用正如第~\ref{sec:method} 节所述我们提出了... 式~\ref{eq:loss} 给出了损失函数的定义。~\ref中的波浪线表示不换行空格它能防止引用编号和前面的文字被分到两行这是排版细节里很重要的一个点我在写论文时发现很多人的引用编号跑到了行首就是因为没加这个波浪线。6. 从入门到入坑常见报错与我的排查记录配环境不算难真正让人摔跟头的是各种编译报错。我把自己这几年踩过的坑整理一下按发生频率从高到低排列。6.1 坑之一编译时报错却看不到错误信息现象保存文件后右下角弹出一条错误提示但是点开详情发现只有一句 Recipe terminated with fatal error。排查链路打开 VS Code 的输出面板CtrlShiftU在下拉框里选择 LaTeX Workshop。找到日志里Error或者!开头的行比如! LaTeX Error: File xxx.sty not found.。针对这个错误去修复缺宏包就把宏包下载下来TeX Live 一般自带MiKTeX 需要在线安装缺文件就检查路径。这一步看起来很简单但很多人第一次遇到时会不知所措因为 VS Code 默认不弹出错误详情弹窗出于避免打扰的考虑它是静默编译的。所以排查 LaTeX 报错的第一步永远是看 Output 面板的 LaTeX Workshop 日志而不是瞎猜。6.2 坑之二编译能出 PDF但中文全乱码或直接报错现象用了documentclass{article}并在正文写中文编译报 Undefined control sequence 或者出现方框乱码。原因默认的 article 文档类不支持中文非 UTF-8 编码或者使用了 pdflatex 引擎但没配置中文字体。解决方案两种任选把文档类改成ctexart同时在文件头部加魔法注释% !TEX program xelatex。保持article引入ctex宏包同样用 xelatex 编译。我在 4.3 里推的是方案 1因为ctexart对中文排版做了整体适配标题、摘要、关键词的格式都比较符合中文论文习惯。方案 2 适合英文模板里嵌少量中文的情况。6.3 坑之三参考文献死活不出来现象正文\cite{}标好了bib 文件也创建了但编译后参考文献列表是空的或者只显示[?]。原因编译顺序不对。BibTeX 和 LaTeX 的编译是有依赖关系的需要跑多轮先 pdflatex 生成 .aux、再 bibtex 处理 .bib、再 pdflatex 引入结果、再 pdflatex 更新交叉引用。如果只编译一次参考文献当然不会出现。排查链路打开 Output 面板看日志里有没有运行bibtex这一步。如果没有说明 latexmk 的 recipes 配置不对或者你的文档没有\bibliography{references}。如果 bibtex 跑过了但引文键在 .aux 文件里没找到检查有没有把references.bib文件名写错注意拼写和大小写。如果以上都对看看是不是.aux文件里的引用键和 bib 文件里的article{key}不一致比如两者只差一个空格或一个大写字母。这一点隐蔽且常见。用 latexmk 的好处就是它自动判断编译轮次不会出现编译顺序问题。这也是我在第 2 节说编译方案选 latexmk的原因。6.4 坑之四插图路径和文件名有问题现象编译报File figures/overview.png not found但明明文件就在那个位置。原因可能有三种文件路径写错了比如figures目录的大小写和实际不一致Windows 下大小写不敏感但对某些Linux环境敏感文件名包含空格或中文LaTeX 对这类文件名支持不好你用的是 pdflatex但图片是 EPS 格式而 pdflatex 默认只认部分格式需要改用 xelatex 或 latexdvips。我建议所有图片文件名改成纯英文、纯数字、下划线的组合不要带空格和中文路径统一小写。这能在根源上避免大量低级报错。6.5 坑之五word的latex无法正常显示这是一个我知道但自己没遇到过的问题很多人装完插件后不做设置直接在 Word 里用 LaTeX 模式的公式编辑器发现公式显示不出来。这其实是另一套工具链Word 自带的 LaTeX 公式解析和 VS Code 没有任何关系。如果你在论文写作中遇到类似问题我的建议是不要在 Word 里折腾 LaTeX直接用 VS Code TeX Live 写全文因为 Word 的 LaTeX 支持非常有限而且公式和正文排版风格割裂。6.6 坑之六指向 PDF 的外部查看器没有配置好有的用户喜欢用 SumatraPDF 看最终 PDF但安装了一直打不开 VS Code 里生成的 PDF。原因是 LaTeX Workshop 默认调用内部 PDF viewer需要你手动切换latex-workshop.view.pdf.viewer: external并配置好 SumatraPDF 的路径。这个功能是可选的我一般是先在内部 viewer 快速预览最后定稿时再用外部阅读器通读一遍。不建议一开始就配置外部阅读器徒增复杂度。7. 让写作更高效代码片段、快捷键与我的个人工作流环境跑通了报错会排了接下来就是大量写作的阶段。这个阶段提升效率很关键。7.1 自定义代码片段把常用模板变成快捷键VS Code 支持用户自定义代码片段User Snippets。我给自己配置了几个高频片段比如fig插入图片模板、eq插入公式、tbl插入表格。具体操作CtrlShiftP→ 输入Configure User Snippets→ 选择latex→ 粘贴。{ Figure: { prefix: fig, body: [ \\begin{figure}[H], \\centering, \\includegraphics[width0.8\\textwidth]{$1}, \\caption{$2}, \\label{fig:$3}, \\end{figure}, ], description: Insert a figure environment }, Equation: { prefix: eq, body: [ \\begin{equation}, \\label{eq:$1}, $2, \\end{equation}, ], description: Insert an equation environment } }配置之后输入fig再按 Tab就会自动展开成一个完整的 figure 环境光标自动跳到第一个需要填写的位置。重复性的格式书写被省掉了写作节奏会流畅很多。7.2 我个人的写作工作流我的流程是这样的供参考先写大纲在 main.tex 里只写章节结构section 标题不用管具体内容。按章填充从引言开始一章一章地写。每写完一节保存自动编译肉眼检查 PDF。边写边标凡是需要补数据、补引用、补图表的地方写上% TODO: ...注释。VS Code 的 UI 里能高亮 TODO 注释吗不能但你可以用TODO Highlight插件让它高亮。排版收尾所有内容写完后统一调整图表位置、公式换行、引用格式。这一步我通常关掉 autoBuild手动按CtrlAltB编译避免频繁编译浪费时间。终稿检查生成 PDF 后通读一遍重点看目录页码、图表的编号、参考文献的格式是否符合模板要求。这个工作流的核心思想是把写作和排版分成两个阶段。写初稿时不用管格式只专注内容。等所有内容都在了再做格式微调。LaTeX 只要你不改格式指令重编译不会改变之前的排版结果所以不用担心调完这章上章格式崩了这种 Word 经典问题。7.3 远程工作与版本管理到这个层面我默认你已经解决了基本环境问题。如果你像我一样有两台电脑家里和实验室建议给项目做两层保障把整个论文项目放进 Git 仓库每次修改的提交信息写清楚修改实验结果表格、补了第2章参考文献这样出问题时可以回滚。如果需要在云上同步可以用 GitHub 私有仓库或者用 Overleaf 在线协作前提是你愿意把本地项目搬到网页端。但注意Overleaf 用的宏包版本和本地 TeX Live 可能不一致大概率会出现本地编译通过、网页端报错或者反过来的情况我这里只是提示一下不深入展开。7.4 我对 VS Code 写 LaTeX 的整体评价说了这么多坑但我的结论依然很明确这套组合值得花一个下午去学习配置。它本质上的优势不是好看而是单一编辑器同时搞定代码、文本、编译预览、终端和 Git配置可复制换电脑之后 10 分钟就能还原整套环境基于文本的 LaTeX 源码天然适合版本管理多人协作时不会像 Word 那样出现最终版2最终版3这种文件地狱。回到标题里的 从入门到入坑——我最初以为入坑是贬义后来发现这个坑其实指的是从此回不去 Word 的坑。配置 LaTeX 的过程确实有几道坎但踏过去之后后续的论文写作效率提升是实打实的。如果你正在第一篇论文门口犹豫照着这篇文章把环境搭好写满两页内容一旦 PDF 出来那种成就感会让你觉得一切折腾都值。