写 LaTeX 这事儿，我绕了不少弯路。最早用的是某在线协作平台，网络一波动就难受；后来切到某个一体化套装，编译按钮倒是方便，可代码补全和 Git 集成又跟不上。最后稳定在了 VS Code + TeX Live 这条路上，一用就是好几年。如果你正准备搭环境，或者正被其他编辑器的各种小毛病折磨，这篇就按我实际踩过的路子，把从安装、配置到写出一份能看的 PDF 的完整过程捋一遍。
先说结论：VS Code 本身只是个壳子，真正的排版引擎来自 TeX Live。编辑器负责让你写得舒服，TeX Live 负责编译出 PDF，而连接这两者的桥梁是 LaTeX Workshop 这个扩展。三者分工明确，缺一不可。下面我从方案选型讲起，再一步步带你把手动配置和日常使用里的门道都过一遍。
1. 方案选型：为什么是 VS Code + TeX Live
1.1 工具链里的三个角色
很多人刚接触 LaTeX 时，容易被“装一大堆软件”这件事劝退。其实拆开看，整套工具链只分三层。
底层是 TeX Live，它是一个发行版，负责把 .tex 源码变成 PDF。里面包含了编译引擎（比如 pdfLaTeX、XeLaTeX、LuaLaTeX）、几百个宏包，以及字体、文档类等基础资源。收了论文模板或期刊要求的特殊宏包时，你会特别感激 TeX Live 的宏包仓库足够全。
中间层是 VS Code。它本身不认识 LaTeX，但可以安装 LaTeX Workshop 扩展，把编辑器变成集成开发环境：有语法高亮、代码折叠、自动补全、一键编译、PDF 预览、反向定位。
我个人还把 Git 集成也算在这层。写学位论文或长期项目时，版本回滚的重要性完全不亚于排版本身，VS Code 的源代码管理面板直接嵌进窗口，不用切工具。
最上层是你自己的 settings.json 和代码片段。LaTeX Workshop 默认配置在简单场景下够用，但真正顺手的工作流，几乎都要改几处编译配方和自动清理规则。这部分是拉开体验差距的关键。
1.2 对比在线平台和其他本地工具
先说在线平台。它零安装、实时协作这些优点确实无解，但对我来说有几个硬伤：一是需要网络状态良好，二是版本管理困难，三是某些宏包受限。写简单文档无所谓，做正式课题或提交期刊模板时，还是本地环境更可控。
有人会推荐专用的 LaTeX IDE，它们的按钮化操作确实对新手友好。可一旦项目变大，你大概率还是需要在宏包、索引、术语表、参考文献之间做精细控制，专用 IDE 的抽象封装反而会挡路，出问题时你更不知道该去查哪一层。VS Code 虽然多一步手写 JSON 配置，但它把底层的编译命令暴露得很直白，本质上是把选择权还给你。
还有一派喜欢用 Vim/Emacs 的，我也用过一段，坚持下来的是少数。整个学习曲线太陡，日常使用中要记的快捷键和插件配置会分散注意力。VS Code 算是在“编辑器易用性”和“深度定制能力”之间取了个中间值，对多数人来说是投入产出比最高的选择。
选择 TeX Live 而不是其他发行版，也有原因：跨平台、宏包集合最全、每年更新稳定。Windows 上安装时选“安装全部宏包”，看起来体积大，但能省掉后面缺包时单个安装的折腾，这一点在写跨章节参考文献和复杂浮动的论文时尤其值得。
2. 从零到一：搭建可用的本地 LaTeX 环境
2.1 安装并验证 TeX Live
TeX Live 的安装方式根据操作系统略有区别。Windows 上推荐用官方安装包，图形界面里选择“安装全部方案”，路径建议不要带空格。macOS 用户可以用 MacTeX 发行包，体验更接近原生应用。Linux 发行版一般自带 texlive-full 或 texlive-latex-extra，但版本可能滞后，需要特定宏包时你可能会想要官方安装脚本。
装完之后如果不确定是否成功，打开终端运行以下命令验证：
latex --version xelatex --version tlmgr --version能看到版本号，说明环境就绪。我第一次安装时漏掉了 PATH，终端怎么都找不到 latex 命令，最后发现是安装时没有勾选“修改系统环境变量”那个选项。重装虽然能解决，但更稳妥的做法是手动把 TeX Live 的 bin 目录加入 PATH，Windows 一般是C:\texlive\2024\bin\windows。
安装全部宏包会占几个 GB 的磁盘空间，属于正常现象。如果确实空间紧张，可以只装常用的 schemes，但遇到宏包缺失时，需要会用包管理器单独补装。我的习惯是一步到位全装，毕竟硬盘比时间便宜。
2.2 安装 VS Code 和 LaTeX Workshop
VS Code 本体没什么好说的，只要认准官方渠道就好。装好后进入扩展市场，搜索 LaTeX Workshop。这个扩展是社区里使用最广泛的 LaTeX 解决方案，安装人数非常多。
除了 LaTeX Workshop，我还会装另外两个小扩展：一是代码拼写检查器，写英文摘要时能省去不少尴尬；二是 Git 相关扩展，如果 VS Code 内置功能满足不了，装一个增强插件也不碍事。
不建议一开始就装一堆美化类扩展。刚上手时扩展越多，settings.json 越乱，出错时越难排查。LaTeX Workshop 自带的高亮和折叠已经够用，先把主链路跑通再谈美化。
2.3 初始 settings.json 配置
LaTeX Workshop 的默认配置已经能完成“编译 + 预览 PDF”的基本功能，但有几个地方我不太满意：默认的 PDF 预览是在 VS Code 内部标签页，更常用的是侧边栏视图；默认的编译配方有时会选错引擎；编译产生的辅助文件也不清理。
以下是一份我梳理过的初始配置，把它放进用户设置或项目.vscode/settings.json里都行：
{ "latex-workshop.latex.autoClean.run": "onBuilt", "latex-workshop.latex.clean.subfolder": true, "latex-workshop.latex.clean.fileTypes": [ "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc", "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.fls", "*.log", "*.fdb_latexmk", "*.snm", "*.synctex.gz", "*.vrb" ], "latex-workshop.view.pdf.viewer": "tab", "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": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "%DOC%" ] }, { "name": "bibtex", "command": "bibtex", "args": ["%DOCFILE%"] } ] }这份配置的核心思路：先定义工具，再定义配方。工具是具体的编译命令，配方是多个工具的编排顺序。我默认选用 xelatex 而不是 pdflatex，是因为处理中文字体时 xelatex 更可靠，现在高校和期刊模板也基本转向 xelatex。
autoClean.run: "onBuilt" 表示每次编译成功后自动清理辅助文件，避免项目目录里散落几十个中间文件。如果你用的模板需要 .toc 或 .bbl 参与下一次编译，清理必须在编译结束之后进行，这个配置按顺序执行，不会干扰。
3. 核心配置解析：从一键编译到反向定位
3.1 编译配方与 Magic Comment
LaTeX Workshop 的编译逻辑不是“点一个按钮”，而是通过配方来串联工具链。上一节我给的是最小配方，但正式写论文时只跑一遍 xelatex 往往不够。比如有参考文献和交叉引用时，标准流程是编译两次，再配合索引工具，顺序错了就得不到正确结果。
更灵活的做法是在 .tex 文件第一行写“魔法注释”，让每个文件绑定自己的编译流程。我的论文主文件开头是这样写的：
% !TEX program = xelatex % !BIB program = bibtex \documentclass[12pt]{book}第一行指定主编译器，第二行指定参考文献工具。LaTeX Workshop 会优先读取这些注释，忽略默认配方。这个机制很适合同时维护文档和论文的情况：一份项目里既有中文报告用了 xelatex，又有英文短文想用 pdflatex，魔法注释可以逐文件指定，不必全局切换设置。
魔法注释开头必须是% !TEX，中间不能有多余空格。我就因为手滑写成了%!TeX导致它没被识别，编译用的还是旧配方，排查了好一阵才发现是少了空格。写成% !TEX是稳定的写法。
3.2 正向搜索与反向定位
LaTeX 编辑最大的爽点之一，是能实现“源码位置 ⇌ PDF 位置”互跳。LaTeX Workshop 通过 SyncTeX 机制完成这个功能。它依赖编译时生成的.synctex.gz文件，所以编译命令里必须带上-synctex=1参数，这就是我在工具 args 里加这个参数的原因。
从源码定位到 PDF 很简单：光标停在正文对应位置，按快捷键执行“SyncTeX from cursor”。VS Code 里默认的快捷键组合是 Ctrl+Alt+J（macOS 上对应 Cmd+Option+J），PDF 预览窗口会自动跳到对应位置并高亮。
从 PDF 定位回源码则需要先在 PDF 预览中按住 Ctrl 并单击某段文字，编辑器会自动跳转到对应行。校对稿子时这个功能非常顺手，上一轮导师批注的“请在第 42 行核对”，几乎能瞬间定位。
如果没有生效，按三个方向排查：第一，编译命令是否带-synctex=1；第二，PDF 预览是否用的是 LaTeX Workshop 自带的 viewer，外部 PDF 阅读器一般也能支持，但需要在设置里开通外部查看器的 SyncTeX 通信；第三，编译后是否有 .synctex.gz 文件存在。
3.3 自动编译触发方式
LaTeX Workshop 支持两种自动编译：一种是一保存就编译，另一种是加了延迟的防抖编译。我推荐开启latex-workshop.latex.autoBuild.run为onSave，配合 1~3 秒延迟，既不用手动按编译，又能避免频繁刷新导致的问题。
不过我自己在写长文档时，会把这个自动编译关掉，改成手动触发。原因是章节多、图多的时候，每次都全量编译会浪费大量时间，自动刷新反而干扰思路。反而在改公式或微调文字的阶段，自动编译能带来立竿见影的反馈。
更精细的控制可以通过快捷键完成。默认情况下 Ctrl+Alt+B 编译，Ctrl+Alt+V 打开 PDF。如果和系统其他软件快捷键冲突，可以在 settings.json 里重新绑定。快捷键绑定是编辑器体验中最容易被低估的一环，值得花 10 分钟按自己习惯调一遍。
3.4 编码与字体处理
日常写中文文档，第一个面对的问题是编码。现代 TeX Live 和 VS Code 对 UTF-8 的支持已经很成熟，只要确保 .tex 文件以 UTF-8 保存即可。VS Code 默认就是 UTF-8，一般不会出问题。
真正容易踩坑的是字体。xelatex 可以直接调用系统中的字体，比如中文字体设置成宋体、黑体、楷体等。一个基础配置是这样：
\usepackage{fontspec} \usepackage{xeCJK} \setCJKmainfont{SimSun} \setCJKsansfont{SimHei} \setCJKmonofont{KaiTi}这里需要注意字体名称必须是系统中安装的真实字体名，Windows 里的中文字体名是 SimSun，macOS 可能是 Songti SC。字体名写错了，编译时会报“font not found”之类的信息。你可以用系统自带工具或命令列出可用字体，再回填到文档里。
如果模板需要的是 Times New Roman 这类西文字体，可以用 fontspec 的\setmainfont{Times New Roman}设置。整个字体处理思路就是从“TeX 自己带字体”切换到“让系统字体为 TeX 所用”，这也是 xelatex 相比老式编译器的核心优势。
4. 实操编写细节：从模板到正式文档
4.1 先搭框架再填内容
很多人写 LaTeX 的毛病是一上来就逐字逐句地写正文，结果结构混乱、前言后记对不上。我的习惯是先搭一个最小可编译的框架，再往里面填章节。主文件结构大致是这样：
\documentclass[12pt,a4paper]{ctexart} \usepackage{graphicx} \usepackage{amsmath} \usepackage[style=gb7714-2015]{biblatex} \addbibresource{refs.bib} \title{基于某方法的实验研究} \author{某开发者} \date{\today} \begin{document} \maketitle \tableofcontents \section{引言} \section{相关工作} \section{实验设计与结果} \section{结论} \printbibliography \end{document}先让这个空壳正常编译出 PDF，再逐个章节填充。这样能保证排版问题在早期就被发现，不会等到写了几十页才爆出格式错误。
用 ctexart 文档类而不是标准的 article，是因为它已经封装好了中文排版和字体的基础配置，不需要自己手动画瓢。当然，如果学校有指定模板，直接以模板为准。
4.2 常用代码片段提升效率
VS Code 支持自定义用户代码片段（User Snippets），我强烈建议在 LaTeX 里配几个高频片段。每次手打\begin{...}...\end{...}效率很低，片段可以一键生成结构。以figure为例：
"LaTeX figure": { "prefix": "fig", "body": [ "\\begin{figure}[htbp]", " \\centering", " \\includegraphics[width=0.8\\textwidth]{${1:fig}}", " \\caption{${2:这是图注}}", " \\label{fig:${3:label}}", "\\end{figure}", "" ] }配置片段的位置在“首选项”里的“配置用户代码片段”，选择 LaTeX 语言后粘进去即可。类似地，我会给表格、定理、公式都配置片段，写起来像拼积木一样。这个习惯省下的时间在长文档里特别明显。
不过片段也不是越多越好，只配自己每天都会写的结构。否则补全列表会很长，反而影响选择速度。
4.3 参考文献的两种管理思路
参考文献是 LaTeX 初学者的另一道坎。我经历过两个阶段：早期直接手写 thebibliography 环境，后来改用 BibTeX 或 biber 统一管理。手写的优点是简单直接，缺点是文献一多就难以排序、去重、换样式。
用 BibTeX 时，文献条目放在.bib文件里，正文引用\cite{key}。编译时必须走完整的工具链：编译一次 → 跑 bibtex → 再编译两次。所以我的配方里专门有xelatex -> bibtex -> xelatex -> xelatex这一条，就是为文献准备的。
如果期刊要求的是作者-年份制，而不是数字上标制，一般需要切换到 biblatex 配合 biber。那配置里还要把 bibtex 工具换成 biber。这部分要依据具体模板要求来调整，别盲目照搬网上配置。
4.4 编译状态面板解读
LaTeX Workshop 左侧侧边栏里有个 TeX 面板，里面能看到当前打开文档的编译日志、配方选择、清理文件、语法检查等入口。初看会觉得花哨，实际最常用的是两个：
第一个是“日志”面板，编译出错时它会列出所有错误信息。默认界面会把 LaTeX 日志里的大段内容原样显示，看起来非常劝退。我习惯在设置里开启错误解析智能化，让 LaTeX Workshop 把每一条错误和源码行对应起来。
第二个是“构建”区域，里面能看到当前用的配方名字。如果你改了魔法注释或配置，重新点一下“构建”看看用的配方是不是预期的，能提前排除大半编译问题。
4.5 与 Git 协作时的文件组织
用 Git 管理 LaTeX 项目时，最大的坑是一堆 .aux、.log 文件也被记录进去了。这些文件每次编译都会变，提交后会制造大量无意义的 diff。我的建议是加一个.gitignore，把构建辅助文件和 PDF 都忽略掉。PDF 如果真需要共享，可以用 release 分支或 git-lfs 管理。
.gitignore内容大致如下：
*.aux *.log *.out *.toc *.bbl *.blg *.fls *.synctex.gz *.fdb_latexmk *.pdf把这个文件放进项目根目录，能让你在回顾 Git 历史时只看得到 .tex、.bib 和图片资源，提交记录干净清爽。
5. 踩坑与排查：高频问题速查与实战技巧
5.1 编译失败的定位思路
无论配置多顺手，LaTeX 迟早会报错。我的经验是不要被大段英文吓到，先看错误码和行号，再看具体源码。LaTeX Workshop 能在“问题”面板里列出编译时的错误和警告，我排查时最先看这里。
常见的错误大致分四类。第一类是语法错误，比如漏了大括号、写了非法字符；第二类是宏包缺失，TeX Live 全量安装一般不会有这种问题；第三类是字体找不到，xelatex 场景下很常见；第四类是双向引用未定义，经常发生在改了标签名却没有同步更新正文引用时。
定位时我会逐个双击“问题”面板里的条目，VS Code 会跳到对应行。修改后重新编译，很多错误会在第二次编译中消失，因为 LaTeX 辅助文件需要多轮迭代才稳定。
5.2 高频问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 编译后 PDF 不更新 | 未开启自动构建，或 PDF 文件被外部阅读器占用 | 开启 autoBuild.onSave，或关闭外部阅读器里的文件锁 |
| 中文显示为方框 | 未用 xelatex 编译，或未加载 ctex 相关宏包 | 切换编译配方为 xelatex，使用 ctexart/ctexbook 文档类 |
| 参考文献显示 [??] | 未完整执行 bibtex 编译流程 | 选择带 bibtex 的配方，按顺序编译 |
| SyncTeX 点击无效 | 编译参数缺 -synctex=1 | 在工具 args 中补齐该参数 |
| 编译报文件未找到 | 文件路径或文件名包含空格 | 安装 TeX Live 的路径和项目路径都不要带空格 |
| 宏包缺失 | 安装方案不完整 | 用 tlmgr 安装缺失宏包，或改选全量安装 |
| 编辑器提示命令不存在 | PATH 未配置 | 将 TeX Live 的 bin 目录加入系统 PATH |
这个表单里的问题，我在教学和练习中反复碰见，也帮不少人做过远程排查。多数问题不是 LaTeX 本身难，而是工具环境链条中某个环节没接上。
5.3 独家避坑心得
有一类坑特别隐蔽，就是编辑器保存编码与 TeX 引擎读入编码不一致。虽然现代工具默认 UTF-8，但如果用旧模板，或者某次不小心把文件保存成 GBK，再编译就会出乱码。VS Code 右下角有当前文件编码显示，检查并统一为 UTF-8 能避免这一整类问题。
另一类坑涉及临时文件的依赖关系。有时候第一遍编译生成了的是旧的 .aux 文件，第二遍编译却因为中途报错，没有重新生成最新的交叉引用，最终 PDF 中序号和引用对不上。解决方式是把项目目录下的辅助文件删干净，或者直接执行 LaTeX Workshop 的“清理辅助文件”命令，然后连续编译两次。
最后说说同步预览设置。我建议将 PDF 预览模式从tab改成browser或tab都可以，但需要保持固定一个，不要混合使用。我遇到过在内部 tab 和外部浏览器之间来回切换，结果 PDF 不刷新，浪费了不少时间。保持一种预览方式，配合自动清理文件，整个写作体验会稳定很多。
5.4 长文档写作时的三个实战技巧
写学位论文这种几十页的长文档时，只靠一个 .tex 文件会非常痛苦。我的做法是使用\input或\include拆分子文件。主文件负责加载宏包和设定整体布局，每个章节一个子文件，维护起来清楚得多。VS Code 的 LaTeX Workshop 也支持跳转到子文件内部的定义，不用担心拆开后补全和定位失效。
第二个技巧是利用\label和\ref管理图表和公式编号，而不是手工写死。手工写编号最大的问题是插入一个新的图表后，后面所有编号都得手动改，而 LaTeX 自动编号能彻底解决这个问题。代价是写正文时就要顺手补 label，推荐采用“图注写完立刻写 label”的节奏。
第三个技巧是给公式和关键术语建立统一的宏定义。比如全文统一使用\newcommand{\dd}{\mathrm{d}}，可以让微积分符号风格一致；统一定义向量、矩阵、实部虚部等符号命令，改规范时只需要改宏定义，不用全文搜替换。这个习惯让文档维护成本大幅下降。
写在最后
从 TeX Live 安装到 VS Code 配置，从第一份 PDF 到几十页的论文，整个过程本质上就是把这套工具链反复打磨成贴合自己写作习惯的过程。现在回头看，最大的体会是：先跑通最小链路，再去优化细节。很多人装了半小时软件，看完一篇教程就开始折腾复杂配置，结果哪一环出错都不知道。我调试配置的顺序向来是“能编译通 → 能自动编译 → 能定位 → 再谈美观和效率”。
日常写作时有个小配置让我非常受益：写论文时开着自动清理辅助文件，写书稿时反而让它保留 .toc 和 .aux 文件，因为章节多、交叉引用多时需要多轮编译才能稳定。这个差异是很多教程不会提的细节，但正是这种细碎经验，才让整个写作流程变得真正顺手。
如果你正准备入坑 LaTeX，记住：别怕报错，报错信息就是你的调试线索。按上面这套流程搭好环境，后续遇见问题就知道该到哪个环节去查。希望这篇经验能帮你少走一些弯路。
