第一次把 LaTeX 和 VSCode 拼在一起用是帮朋友改一篇投稿论文的时候。他原来的工作流是 Word 里敲公式截图贴进去改到第三轮公式编号全乱了参考文献也对不上号。我当时跟他说你这不是排版问题是工具选错了。LaTeX 负责内容和格式分离VSCode 负责给你一个顺手的编辑器两者组合起来是一套能长期用下去的环境。这套东西的安装和配置确实有点门槛网上教程又大多只给步骤不说原因装到一半卡住的人特别多所以我把从零开始到跑通第一篇文档的完整过程整理出来包括TeX Live 的安装、VSCode 的配置、LaTeX 基础语法、中文支持、公式图表以及最要紧的编译报错定位方法。不管你是写学位论文、投期刊还是纯粹想学一门排版工具这套流程都能直接照着做。1. 为什么我最后留在了 TeX Live VSCode 这套组合上1.1 三个主流发行版之间的真实差异LaTeX 本身只是一套宏命令的规范真正干活的是背后的发行版。目前桌面端能用的主要有三个流派TeX Live跨 Windows、Linux、macOS 三平台安装包完整、宏包齐全MiKTeX是 Windows 上的老牌选手最大特点是按需下载宏包装完体积小MacTeX其实就是 macOS 上的 TeX Live 打包版底层是同一套东西。我推荐新手直接上 TeX Live理由很实在它的宏包生态最全你几乎不会遇到这个包找不到的情况而投稿、写毕业论文这种场景最怕的就是临时缺包。MiKTeX 的按需下载听着很省事但它需要联网一旦网络环境不稳定编译到一半卡在那里等下载体验会非常糟糕。至于安装体积TeX Live 完整版大概几个 GB现在硬盘动辄几百 GB这点空间真不算事。1.2 VSCode 对比专用编辑器的取舍专门给 LaTeX 用的编辑器有一大堆TeXstudio、TeXworks、WinEdt、Overleaf 在线版等等。我早年用 TeXstudio 用了两年功能确实针对性强但有个问题绕不过去你不可能只写 LaTeX。写论文要配 Python 画图做项目要写 Markdown 和代码如果每个语言都装一个编辑器切换成本高插件生态也分散。VSCode 的优势就在这里一个编辑器管所有事情。装了 LaTeX Workshop 之后编译、预览、正反向跳转、错误提示全都有而且和你写 Python、C、Markdown 是同一个界面、同一套快捷键。缺点是配置项多默认设置对新手不算友好所以才有必要把关键配置一项一项说清楚。1.3 这套组合适合谁不适合谁说句实在话如果你只是偶尔排一篇两页的短文或者你的文档里有大量需要多人协作、批注的功能那这套组合不一定对你有好处。LaTeX 的学习曲线真实存在前两周你会觉得处处别扭。但只要你的文档满足下面任意一条这套投入就划算公式数量多、章节交叉引用多、参考文献上百条、格式要求严格到行距字号都指定、需要长期维护和版本管理。学位论文和期刊投稿是最典型的场景表格和公式排版是另一类。至于 VSCode 部分哪怕你不写 LaTeX它本身也值得装。2. 动手装之前先把这几件事想明白2.1 硬盘空间、安装方式与网络准备完整安装 TeX Live 需要预留8 GB 左右的磁盘空间装完之后实际占用通常在 5 到 7 GB 之间。别装到系统盘剩余空间告急的分区里后面补装宏包还会继续占地方。安装方式有两种在线安装器和离线 ISO 镜像。在线安装器体积小但下载过程要拉几个 GB 的数据中途断网就得重来建议用支持断点续传的下载工具先把 ISO 镜像拉下来。国内一些高校和研究机构都有镜像站速度比官方源快不少这个在后续安装界面里可以选择镜像源选一个物理距离近的能省掉大量等待时间。另外提醒一句安装过程中会往系统 PATH 里写东西Windows 上最好用管理员权限运行安装程序否则可能出现环境变量写不进去的情况。2.2 安装顺序为什么必须先装发行版再装编辑器这个顺序不能颠倒。VSCode 里的 LaTeX Workshop 插件本身不包含任何编译引擎它只是一个调用者负责把你写的.tex文件交给外部的xelatex、pdflatex、latexmk这些命令行程序去编译。如果你先装了 VSCode 和插件再去写文档编译时会直接报错说找不到命令新手很容易在这里怀疑人生以为是插件配置错了。正确的顺序是先装 TeX Live确认命令行能用再装 VSCode装插件最后配置编译参数把它们连起来。2.3 三步自检确认安装真的成功了装完之后别急着打开编辑器先开一个命令行窗口依次验证三件事xelatex --version latexmk --version tlmgr --version三条命令都能打印出版本号说明安装和环境变量都没问题。如果提示不是内部或外部命令那基本上就是 PATH 没配好。Windows 上手动添加的路径长这样C:\texlive\2024\bin\windows注意年份目录会随版本变化别照抄。改完 PATH一定要关掉旧的终端窗口重新开一个因为环境变量是进程启动时读取的老窗口里改了也不生效这个坑我踩过不止一次。3. TeX Live 安装过程中没人细说的那些环节3.1 安装界面的选项哪些可以放心默认运行安装程序后会进到一个命令行风格的界面菜单项看着挺唬人。第一次装的人容易在 scheme 选择那里犹豫。简单说scheme-full 是全量安装scheme-medium 是中等scheme-small 是精简。除非你的硬盘真的吃紧否则直接选 full省掉后面找宏包的时间。界面下方还有一个安装 TeX 的目录选项默认在 C 盘。如果你的 C 盘不大这里可以改成 D 盘或者别的数据盘路径里尽量不要有中文和空格虽然现在的工具链基本都支持了但某些老旧的宏包和脚本还是会在带空格的路径上翻车。3.2 安装要多久中途能做什么完整安装根据磁盘速度和镜像源质量通常要20 到 60 分钟。这期间别去动那个窗口也不要运行大型程序抢磁盘 IO。有个细节安装程序最后一步会执行一些事后处理把字体、格式文件注册好这一步看着像卡住了其实是在干活耐心等它出现完成提示。安装完成之后那个命令行窗口里的tlmgr就已经可用了。这个工具是你以后维护环境的主要入口值得记住几个常用命令命令作用tlmgr update --self更新 tlmgr 自身tlmgr update --all更新所有已装宏包tlmgr install 包名补装缺失宏包tlmgr search --global --file 文件名反查某个文件属于哪个宏包最后那条命令特别有用。当编译报错说找不到某个.sty文件时你不用去搜索引擎瞎猜直接用它反查一秒定位到该装哪个包。3.3 环境变量的两个隐蔽坑第一个坑是多版本共存。如果你电脑里以前装过 MiKTeX或者装过旧版 TeX Live 没卸载干净PATH 里可能有两套路径命令行调用到的未必是你新装的那个。用where xelatexWindows或者which xelatexLinux/macOS看一下实际路径确认指向的是新版本。第二个坑是编辑器继承了旧的环境变量。VSCode 如果是安装 TeX Live 之前就打开的它内部的终端和插件进程读到的还是老 PATH。这时候你在 VSCode 里编译死活失败但外部命令行明明正常。解决办法很土但很有效把 VSCode 完全退出不是关窗口是退出进程再重新打开。3.4 缺宏包不要慌补装比重装快得多写论文时最常见的突发状况是别人给的模板编译报错提示某个宏包缺失。这时候千万别想着重装整个发行版直接用tlmgr install补上就行。比如模板里用到了algorithm2e和booktabs你就执行tlmgr install algorithm2e booktabs如果报错说宏包名不对先用tlmgr search --global --file algorithm2e.sty反查一下准确名称。还有一种情况是模板要求某个宏包的特定版本TeX Live 自带的是新版语法有变化这就得看模板作者的说明了属于比较少见但要心里有数的情况。4. VSCode 这一端的配置让插件真正跑起来4.1 基础安装与界面语言VSCode 从官网下载对应系统的安装包Windows 上建议勾选添加到 PATH这一项这样以后在命令行里敲code .就能直接打开当前目录。安装完成后界面语言默认跟随系统想手动切成中文的话在扩展面板搜索中文语言包装上重启即可。这一步不影响 LaTeX 使用纯属个人习惯但中文界面在排查插件配置项时反而更容易看错术语我个人建议保持英文界面配置项名称和网上文档能一一对应上。4.2 LaTeX Workshop 的核心设置项在扩展面板搜LaTeX Workshop认准作者是 James Yu 的那个安装量最高。装完之后它其实已经能用了默认会尝试自动编译。但默认配置有几个地方我不满意它会自动清理辅助文件、编译工具固定用 latexmk、错误提示不够醒目。所以我会改一份设置。打开设置界面找到在 settings.json 中编辑把下面这些写进去{ latex-workshop.latex.autoBuild.run: onFileChange, latex-workshop.view.pdf.viewer: tab, latex-workshop.latex.clean.subfolder.enabled: true, latex-workshop.latex.autoClean.run: onBuilt, latex-workshop.message.error.show: true, latex-workshop.latex.outDir: %DIR%/build }逐条解释一下。autoBuild.run设成onFileChange表示保存文件就自动编译比默认的onSave更顺手viewer设成tab让 PDF 在编辑器旁边的标签页里打开而不是弹独立窗口outDir把编译产生的中间文件全部丢进build子目录源码目录会干净很多这点在配合 Git 版本管理时尤其重要你只需要在.gitignore里忽略build/就行。4.3 编译链配置为什么中文要用 xelatex默认的编译链用的是latexmk它内部调pdflatex。这套组合处理英文文档没问题但中文会直接报错或者编译出乱码因为pdflatex对 Unicode 和系统字体的支持很有限。中文文档的标准做法是换成xelatex或者lualatex前者更快更稳后者对 Lua 脚本支持好。我一般配两条链一条英文快速编译一条中文完整编译{ latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] }, { name: xelatex - bibtex - xelatex*2, tools: [xelatex, bibtex, xelatex, xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ] }这三个参数值得单独说。-synctex1生成正反向跳转所需的数据-interactionnonstopmode让编译遇到错误时不弹交互提示否则自动化编译会卡死等待输入-file-line-error是最有用的一个它把错误信息格式化成文件名:行号: 错误描述配合编辑器的错误面板你能直接点一下跳到出问题的那一行排查效率提升非常明显。4.4 正反向搜索与多文件项目管理正反向搜索是这套组合真正爽的地方。配好之后在源码里按 CtrlAltJPDF 会跳到对应的位置在 PDF 里按住 Ctrl 点击某处编辑器会跳回对应源码。用之前要确保编译时带了-synctex1并且 PDF 是通过 VSCode 打开的用外部阅读器打开这个功能就失效了。如果你的论文分成了多个.tex文件主文件用\input或\include引入子文件那必须在设置里告诉插件哪个是主文件{ latex-workshop.latex.rootFile.useSubFile: false, latex-workshop.latex.rootFile.doNotPrompt: true }更直接的办法是在主文件第一行加一句魔法注释%!TEX root main.tex插件会识别它。这样你在子文件里按编译它也会去编译主文件不会出现编译单个子文件报错的怪事。5. 写出第一篇能编译的中文文档5.1 文档骨架与中文宏包的选择一个最小的中文文档长这样\documentclass[12pt, a4paper]{ctexart} \usepackage{amsmath, graphicx} \title{学习笔记} \author{我} \date{\today} \begin{document} \maketitle \section{开篇} 这是一段中文正文用来验证中文排版是否正常。 \end{document}关键在于\documentclass里的ctexart。这套ctex系列文档类把中文字体、行距、段落缩进、标点挤压这些细节都处理好了你不需要自己去配字体。对应的还有ctexrep报告和ctexbook书籍。如果投稿模板强制要求用article那就改成article再手动加载ctex宏包效果一样。字体这件事值得多提一句。ctex默认会调用系统中的中文字体Windows 上是宋体黑体之类Linux 上可能需要额外配置。如果编译报错说找不到字体最简单的办法是显式指定字体名或者改用\usepackage[fontsetfandol]{ctex}用 TeX Live 自带的 Fandol 字体虽然字形一般但至少能编译出来应急够用。5.2 第一次编译从报错到成功的完整过程新建.tex文件贴入上面的代码保存。如果你配了自动编译几秒后就会看到 PDF 预览标签页出现。如果没配点左侧栏的 LaTeX 图标展开 Build LaTeX project选你配好的 recipe。第一次编译大概率会遇到报错。别慌看两个地方编辑器的问题面板会列出格式化的错误行输出面板会打印完整的编译日志。常见的第一次报错有三种一是中文显示为方块或乱码说明编译引擎没用xelatex二是报File xxx.sty not found用前面说的tlmgr install补包三是报某一行有非法字符通常是从网页复制内容时带进了不可见字符。5.3 换行符到底怎么打这个问题被问得太多了值得单独说。LaTeX 里换行其实有三种不同含义很多人混着用结果排版效果和预期完全不一样段落内强制换行用\\或者\newline后面的内容会另起一行但仍属于同一个段落段首不缩进。另起一个段落在源码里空一行或者用\par命令。这样会新起一段并且按照文档类设置自动缩进。分页用\newpage或\clearpage这是换页不是换行。\\还有个副作用要提醒它后面不能紧跟着空行也不能放在段落末尾否则会报Theres no line here to end。所以别习惯性地在每段末尾都加\\该用空行的地方就用空行。表格和公式环境里\\是标准换行符那是另一套规则别拿正文的习惯去套。6. 公式、插图、表格这三个高频动作6.1 数学公式的两种写法和符号速查行内公式用一对美元符号包裹比如$E mc^2$它会嵌在文字中间。独立成行的公式用equation环境会自动带编号\begin{equation} f(x) \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2\pi i \xi x} \, d\xi \end{equation}需要多行对齐就用align环境用标记对齐位置\\换行这两者要用amsmath宏包。希腊字母是必背的\alpha\beta\gamma\theta\lambda\mu\pi\sigma\phi\omega大写形式一般把首字母大写比如\Gamma\Delta\Omega。常用符号里\times是叉乘\cdot是点乘\leq\geq\neq\approx\in\subset\infty\sum\prod这些建议一次性记住。有个省事的技巧VSCode 装个 LaTeX 符号面板插件或者用 LaTeX Workshop 自带的 snippet输入\beg按 Tab 自动补全成环境。我还会在文档里维护一个我自己常用的符号小抄文件写着写着就形成肌肉记忆了比翻符号大全快得多。6.2 插图与浮动体的定位控制插图需要graphicx宏包基本写法是\begin{figure}[htbp] \centering \includegraphics[width0.8\textwidth]{figures/result.pdf} \caption{实验结果对比} \label{fig:result} \end{figure}[htbp]是位置提示依次表示这里、顶部、底部、独立页LaTeX 会按这个优先级尝试摆放。很多人抱怨图片乱跑就是没理解它是建议而不是命令。真要强制固定在当前位置加载float宏包后用[H]参数就可。图片格式上pdflatex和xelatex都支持 PNG、JPG、PDF矢量图优先用 PDF 或者 EPS 转 PDF位图放大会糊。路径建议单独用\graphicspath{{figures/}}声明一次后面就不用每次写完整路径了。引用图片用\ref{fig:result}注意编译需要跑两遍第一遍生成标签第二遍才填上引用编号。6.3 表格自动换行的几种可行方案表格是 LaTeX 里最让人头疼的部分尤其是单元格内容长的时候用标准tabular环境会横向溢出页面。核心原因是l、c、r这三种列格式的宽度是自适应的不会主动换行。解决方案有三种。第一种最基础把列格式换成p{宽度}比如p{3cm}这样该列会固定宽度并自动换行缺点是宽度要手算。第二种用tabularx宏包加X列格式它会自动把剩余宽度平均分配给 X 列\begin{tabularx}{\textwidth}{l X X} \toprule 方法 优点 缺点 \\ \midrule 方法A 速度快适合大规模数据 精度略低需要调参 \\ 方法B 精度高 计算开销大 \\ \bottomrule \end{tabularx}第三种是makecell宏包允许你在单元格里手动换行适合个别单元格内容特别长的情况。另外强烈建议配合booktabs宏包用\toprule\midrule\bottomrule三条线学术表格的规范画法就是不用竖线、只用横线出来的效果干净很多。7. 编译报错时怎么快速定位到那一行7.1 读懂编译日志的正确顺序LaTeX 的报错有个特点第一个错误往往才是真凶后面的错误全是它引发的连锁反应。所以读日志要从上往下找到第一条以!开头的行。如果你配了-file-line-error格式会是./main.tex:42: Undefined control sequence直接告诉你是第 42 行。没有这个参数的话格式是这个样子! Undefined control sequence. l.42 \someunknowncommandl.42就是行号。看到行号之后去编辑器的问题面板点一下就能跳过去。如果问题面板没显示说明你的日志正则没匹配上这时候直接打开build目录下的.log文件用编辑器的搜索功能搜!也能快速定位。7.2 常见错误对照表我把这些年踩过的坑整理成一张表按出现频率排序报错信息真正原因处理办法Undefined control sequence命令拼错或宏包没加载检查拼写补\usepackageMissing $ inserted数学符号写在了正文环境给符号加$...$File xxx.sty not found缺宏包tlmgr install xxxRunaway argument花括号没配对检查环境闭合Extra alignment tab表格列数与声明不符数一下的个数Missing number参数位置写了非数字检查长度、计数类参数Emergency stop严重错误被迫中止看前面第一条!错误Font ... not found字体缺失或名称错误换字体集或指定字体名有一点要特别强调报错行号和真正的问题行不一定一致。比如你漏了一个右花括号LaTeX 可能一直读到文件末尾才发现报错行号是最后一行。这时候别死盯着那一行看往上翻找最近的一个\begin是不是没配对的\end。7.3 二分法定位当错误藏在几百行里如果日志指向的行看着完全正常那就是前面某处的语法错误被延迟报了出来。这时候用二分法把文档从中间截断用\end{document}提前收尾看前半部分能不能编译通过。能通过说明问题在后半段继续切不能通过说明问题在前半段继续往前切。这个方法听起来笨但处理大文档时是最快的。我试过在一篇三百多行的模板里找问题二分四次就锁定了具体位置比一行一行看快得多。定位之后记得把临时加的\end{document}删掉这个容易忘。8. 几项真正提升效率的配置和个人习惯8.1 自动补全与代码片段LaTeX Workshop 自带不少 snippet输入\sec按 Tab 会补全成\section{}。你也可以自定义。在设置里找到latex-workshop.intellisense.package.enabled打开插件会读取你加载的宏包自动提示该宏包提供的命令这个功能对记不住命令名的人非常友好。我个人还会装一个拼写检查把中文文档的检查语言设成中文否则满屏红波浪线。方法是在设置里搜cSpell.language加上zh再配一个忽略列表把常见命令名加进去。8.2 版本管理什么时候该用 Git**强烈建议从写第一篇正式文档开始就用 Git。**LaTeX 是纯文本天生适合版本控制而且改论文最痛苦的事就是这版是导师改过的还是我改过的。配合前面的outDir设置源码目录里只有.tex和图片.gitignore里加一行build/就够了。如果图片比较多可以考虑用 Git LFS 管理图片或者干脆把图片单独放一个同步盘目录。提交信息写清楚改了什么章节比写更新有用一万倍。这个习惯在送审前回退到某个版本时会救你的命。8.3 一份可以直接抄的日常操作清单最后把我日常的操作顺序整理一下你可以直接照着用打开项目文件夹VSCode 自动恢复上次的编辑状态。改完内容按CtrlS自动编译触发。看输出面板有没有红色错误有就跳到问题面板处理。没问题的话在 PDF 标签页里滚动检查排版效果。需要核对某处内容时光标放在源码对应行按CtrlAltJ跳转。阶段完成后提交一次 Git写清楚改动内容。定稿前跑一次完整编译链含参考文献那两步把所有交叉引用和目录刷新到位。交叉引用出错、目录编号不对、参考文献编号是问号这些问题九成都是因为编译次数不够。LaTeX 需要多趟编译才能把标签和引用对上所以配置里才会有xelatex - bibtex - xelatex*2这种链。手动编译的话遇到这类问题先连按两次编译再说别急着改代码。顺带说一句如果你除了 LaTeX 还要用 VSCode 写 Python 或者 C环境配置的逻辑是一样的装语言运行时、装对应插件、在设置里指定解释器路径。这套运行时装外部、编辑器只做调用方的思路是通用的理解一次后面装什么语言都不慌。