企业官网建设流程全解析

被 Word 排版折磨过的人，大概率会走上 LaTeX 这条路。目录缩进乱、公式编号要手工改、参考文献对不上号，这些场景只要一篇长文档就能让你崩溃。而“在 VS Code 中配置 LaTeX 编译环境”，本质上就是把你手头的轻量编辑器升级成一套完整、可控、可复现的排版工具链：编辑 .tex 源文件，保存时自动编译出 PDF，还能在源码和 PDF 之间跳转定位。这篇文章不展开讲 LaTeX 语法，只聚焦环境搭建本身，适合三类人：第一次接触 LaTeX 的新手、在 Overleaf 在线写作但想转移到本地的老手、以及想统一团队写作工具链的开发者。

1. 整体思路：先把 VS Code 和 LaTeX 的分工理顺

1.1 三个角色很容易搞混：编辑器、发行版、编译器

我刚接触这个环境时，最困惑的一点就是“我明明装了 VS Code，为什么不能直接写 LaTeX？”后来才明白，这条链路里有三个完全不同的角色，各管一摊。

VS Code 只是编辑器，负责让你舒服地写 .tex 源文件。真正把 .tex 变成 PDF 的是编译器，常见的是 xelatex、pdflatex 和 lualatex 这一类引擎。而编译器本身不携带任何宏包，比如 ctex、amsmath、graphicx 这些现成的排版工具，它们全部存放在发行版里。发行版就是一套完整的工具箱，里面既装了编译器，也装了成百上千个宏包。Windows 上最流行的是 TeX Live 和 MiKTeX，macOS 和 Linux 上通常直接用 TeX Live。

打个比方：.tex 文件是你的菜谱，发行版是装满食材和调味料的厨房，编译器是做菜的那个动作。你平时改的是菜谱，但真正端上桌的菜，是厨房和做菜动作一起配合的结果。很多人配置失败，不是因为 VS Code 设置错了，而是发行版没装好或者装完没生效。

1.2 为什么选 VS Code，而不是 TeXstudio 或者 TeXmaker

市面上有现成的 LaTeX 专用 IDE，比如 TeXstudio、TeXmaker，它们的优点是开箱即用，打开界面就能编译。但我的选择是 VS Code，原因是它能胜任的远不止 LaTeX 一件事。

写论文的时候，我经常需要在正文、代码片段、数据图表之间来回切换。VS Code 本身是通用编辑器，写 Markdown、写 Python 脚本、查日志都在同一个窗口里完成，不用在多个软件之间跳来跳去。它和 Git 的集成也做得很好，改了几版论文、哪一行出现了变动，鼠标一点就能看明白。另外，VS Code 的远程开发能力对经常跑实验的人来说非常实用：代码在远端服务器上，但编辑、编译、看 PDF 都在本地完成。

TeXstudio 这类专用工具并不是不好，只是它的定位就是“LaTeX 全家桶”，除了写 LaTeX 之外帮不上别的忙。如果你同时还要写技术文档、写自动化脚本，VS Code 的综合体验会舒服得多。

1.3 LaTeX Workshop 在这条链路里的角色

LaTeX Workshop 插件是整套方案的中枢。它本身不参与编译，它的工作是调用发行版里的编译命令，然后把结果、日志、错误信息统一管理起来。

我在早期看这个插件时，总觉得它很神秘，好像“一键编译”是魔法。实际上它做的事情很简单：读取你的配置，找到 xelatex 这个程序，在终端里执行一条编译命令，再把编译产生的 PDF 显示出来。如果编译过程中有错误，它会解析日志，把具体是哪一行出错标注出来。你不需要手动打开终端去敲编译命令，也不需要自己记住到底要先跑几次 xelatex 才能让目录和引用正常生成。

所以整条链路理顺之后，配置思路就非常清晰了：装好发行版，装好插件，告诉插件“你用哪个工具、按什么顺序来编译”。接下来花时间研究的就是内容本身，而不是环境问题。

2. 环境准备：发行版选型和安装避坑指南

2.1 TeX Live 和 MiKTeX 到底怎么选

这一步是所有人都绕不过去的。发行版选得不对，后面再怎么配插件都是白搭。我把两个主流方案放在一起比了一下。

我最终选的是 TeX Live。最主要的原因是它的宏包完整，离线状态下基本不会出现“缺少 xxx.sty”这类问题，写长文档的时候心态稳定。MiKTeX 的自动补包功能确实贴心，但它在每次联网下载宏包时都可能有版本冲突，我遇到过编译到一半提示“需要安装新宏包”的情况，那感觉并不好。

如果你只是写几页作业、或者临时跑个小文档，MiKTeX 的轻量优势很明显。但如果你要用中文论文模板、要处理 TikZ 绘图、要各种复杂宏包组合，直接上 TeX Live 完整版能省下大量时间。

2.2 安装 TeX Live 之前，先注意这几件事

安装 TeX Live 看起来是“下一步下一步”的事，但有几个细节会影响后面的使用。

第一，磁盘空间要预留足。完整版实际占用可能在 10 GB 上下，安装过程还要临时解压，所以硬盘至少要留出 15 GB 以上的空间。我见过同事为了省空间装了个精简版，结果缺了一堆常用宏包，最后还是要回头补装。

第二，下载安装包建议走国内可用的镜像源。这样可以显著加快下载速度。安装工具通常提供“选择镜像站点”的选项，找到可用镜像即可，选位置近的一般就快。这一步在安装时操作即可。

第三，安装过程不要轻易中断。TeX Live 安装的是一个整体，中途断电、断网都可能导致目录结构不完整。最直观的表现是某些命令能运行，某些命令报“无法找到文件”。遇到这种问题，重装往往比重修快。

第四，装完一定要检查环境变量。Windows 上安装器一般会自动写入 PATH，但终端是安装前就打开的，新加的路径不会立刻生效。正确做法是重新开一个新的命令行窗口，输入xelatex -v看能不能显示出版本号。如果提示“不是内部或外部命令”，说明 PATH 没有生效，需要手动把 TeX Live 的 bin 目录加进去。macOS 和 Linux 上一般不用管，但如果换了自定义安装目录，也建议用which xelatex确认一下。

2.3 验证命令和装完后的第一件事

安装完成后，我习惯在终端里一次性验证三样东西：xelatex -v、latexmk -v、tlmgr --version。第一个确认编译器可用，第二个确认 latexmk 存在，第三个确认宏包管理器正常。latexmk 是一个自动化编译脚本，它会在后面帮我们省很多事。

验证完毕之后，重新启动 VS Code，确认它是新进程而不是旧窗口。如果 VS Code 在安装 TeX Live 之前就打开了，它不会识别新的 PATH。我当时就是因为没重启，一直以为插件配置写错了，浪费了不少时间。

3. 核心配置：LaTeX Workshop 与编译方案定制

3.1 插件安装与初始化

在 VS Code 的扩展商店里搜索 LaTeX Workshop，直接安装。这个插件是整套方案的核心，至于 LaTeX 的语法高亮、文档大纲、代码补全这些基础功能，它都已经包含了。

装完插件后，第一次打开 .tex 文件时会初始化。如果在侧边栏没有看到 TeX 相关面板，检查一下状态栏有没有报错提示。LaTeX Workshop 不会替你安装发行版，它只会提示你“系统中没有找到某个编译器”。之前装的 TeX Live 在这里就派上用场了。

3.2 用 recipes 和 tools 定义编译命令

LaTeX Workshop 的配置核心是两个概念：tools 和 recipes。tools 定义了一条可以执行的编译命令，比如“调用 xelatex 编译当前文件”。recipes 则是把这些 tools 组合起来，形成一个完整的“流程”。

我当前的配置里，最关键的两段就是 tools 和 recipes。打开 VS Code 的设置文件 settings.json，加入下面这段：

{ "latex-workshop.latex.tools": [ { "name": "xelatex", "command": "xelatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC_EXT" ] }, { "name": "latexmk", "command": "latexmk", "args": [ "-xelatex", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC_EXT" ] } ], "latex-workshop.latex.recipes": [ { "name": "latexmk (xelatex)", "tools": ["latexmk"] }, { "name": "xelatex 单次编译", "tools": ["xelatex"] } ] }

几个参数逐个说一下为什么这么写。

-synctex=1是必备项，它让编译器生成源代码和 PDF 之间的同步映射。没有这个参数，正反向跳转就没有数据可用。-interaction=nonstopmode的意思是遇到错误不暂停等待输入，直接往下跑。编译脚本里最怕的就是一个窗口停在“请输入 x 继续”这种状态，这个参数就是为了避免这种情况。-file-line-error让错误输出带上文件名和具体行号，VS Code 才能把报错定位到对应代码行。

%DOC_EXT是插件的内置变量，表示当前打开的 .tex 文件的完整路径，带上 .tex 扩展名那种。这样配置文件就不需要写死文件名，无论打开的是a.tex还是b.tex，命令都会自动替换成正确路径。

3.3 为什么推荐用 latexmk 而不是手动跑多遍 xelatex

写一篇带目录、带参考文献、带交叉引用的文档时，经常需要连续编译多次。第一次编译生成辅助文件，第二次更新引用关系，第三次才能把所有编号最终确定下来。手动敲三遍xelatex main.tex很繁琐，而且容易漏。

latexmk 就是专门解决这个问题的。它会根据 .aux、.toc、.bbl 这些辅助文件的变化自动判断还要不要继续编译，直到所有引用稳定为止。在 recipes 里，我设置了latexmk -xelatex，这是告诉 latexmk：请你使用 xelatex 作为底层引擎。因为默认情况下 latexmk 倾向于调用 pdflatex，但中文文档用 pdflatex 会遇到编码和字体问题。

如果你不想在 VS Code 配置里控制，也可以在项目根目录放一个.latexmkrc文件，内容只有一行：

$pdf_engine = 'xelatex';

两种写法效果一样，选一种你觉得顺手的就好。我个人更喜欢把参数都写在 VS Code 的 settings.json 里，这样整个团队复制同一份配置时，不需要额外分发隐藏文件。

3.4 常用配置项：自动编译、预览、同步、清理

除了编译命令，还有几个配置项对日常体验影响很大。

{ "latex-workshop.view.pdf.viewer": "tab", "latex-workshop.latex.autoBuild.run": "onSave", "latex-workshop.synctex.afterBuild.enabled": true, "latex-workshop.latex.clean.fileTypes": [ "*.aux", "*.bbl", "*.blg", "*.log", "*.out", "*.toc", "*.synctex.gz", "*.fls", "*.fdb_latexmk", "*.xdv" ] }

view.pdf.viewer设为tab，可以让 PDF 在 VS Code 内部标签页打开，不用每次跳转到外部阅读器。autoBuild.run设为onSave，每次保存 .tex 文件就自动编译，体验非常顺滑。synctex.afterBuild.enabled让编译完成后自动建立同步关系，PDF 预览里直接 Ctrl 点击就能跳回源码。

清理辅助文件也很重要。编译一次会生成一堆 .aux、.log、.out 之类的中间文件，这些文件不应该手动删除，因为很多编译状态就是靠它们记录的。但项目做完以后，它们又是一堆垃圾。LaTeX Workshop 里可以一键清理，上面那组clean.fileTypes就指定了清理范围。我一般写完一个阶段性的版本，就清理一次，避免项目目录越来越乱。

3.5 Magic Comment：一行注释让你的项目“自带配置”

还有一个我觉得非常实用的技巧，就是在 .tex 文件第一行写上编译器声明：

% !TeX program = xelatex

这叫 Magic Comment，LaTeX Workshop 会优先读取这一行声明。就算你的全局配置里还写了 pdflatex，或者 recipes 顺序比较乱，只要这一行存在，插件就会优先调用 xelatex。对于需要在多台电脑、多个项目之间切换的情况，这一行注释能避免很多环境差异带来的坑。我所有项目里都会统一约定写这一行。

4. 第一个文档：从空白模板到 PDF

4.1 一份最小可编译的中文模板

配置都完成后，先别急着写长文档，用一个最小的模板把整条链路跑通。中文排版我建议直接用 ctex 文档类，它已经处理好了中文字体、缩进、行距这些细节，不用自己折腾 fontspec 和字体配置。

新建一个文件夹，命名为latex-demo，在里面新建main.tex，内容如下：

% !TeX program = xelatex \documentclass[UTF8,zihao=-4]{ctexart} \title{本地 LaTeX 环境验证} \author{某作者} \date{\today} \begin{document} \maketitle \section{环境验证} 安装并配置完成后，编译以下带引用的测试文档，确认可以正常生成 PDF。 文献引用测试：\cite{example2024}。 \bibliographystyle{plain} \bibliography{refs} \end{document}

zihao=-4的意思是把正文设置为小四号字，这是中文论文常用的字号。UTF8确保源文件按 UTF-8 编码读取。\maketitle会把标题、作者、日期按标准论文格式渲染出来。

还需要在同目录下创建一个refs.bib文件，内容是：

@article{example2024, author = {Example, Author}, title = {An Example Reference}, journal = {Example Journal}, year = {2024} }

这个引用的作用是验证参考文献编译流程。示例条目用的是占位信息，实际写论文时换成你自己的文献即可。

4.2 编译、预览与正反向同步操作

写完模板后，保存 main.tex。如果autoBuild.run已经设为onSave，此时编译就自动开始了。没有触发的话，按默认快捷键Ctrl+Alt+B，或者在侧边栏 TeX 面板里点 “Build LaTeX project”。

编译成功之后，打开 PDF 预览。我在 VS Code 内部标签页看 PDF，这样不需要来回切换窗口。源码和 PDF 的跳转能力是最值得体验的部分：在 .tex 文件里定位到某一行，按Ctrl+Alt+J，PDF 会自动跳到对应位置；反过来，在 PDF 预览页按住 Ctrl 再点击某一段文字，编辑器会自动跳到生成这段内容的源码位置。长文档修改格式时，这个功能能省大量时间。

如果编译失败，不要只看技能错误提示，点开输出面板看完整日志。VSCode 的输出面板其实就是 LaTeX Workshop 捕获到的控制台输出，日志最后出现!符号的行才是真正的根因，上面那些长长的路径和数字通常只是上下文。

4.3 看看 latexmk 做了什么

上面这个模板直接按默认 recipes 编译，latexmk 会自动判断需要跑几次 xelatex，以及是否要调用 bibtex。因为文档里出现了\bibliography{refs}，latexmk 检测到 .aux 文件里有未解析的引用，就会自动去运行 bibtex，然后再回来跑 xelatex，直到引用编号稳定。

不用 latexmk 的话，手动流程是：xelatex → bibtex → xelatex → xelatex。四步缺一步都可能出现“参考文献问号”或“目录编号不对”的问题。这也是为什么我建议直接把 latexmk 作为默认 recipes：自动判断多轮编译顺序，把人为出错的可能性降到最低。

5. 高频问题和排查手册

5.1 常见报错和解决方法速查

整理几个我实际遇到过的经典问题，方便你对着排查。

5.2 我感觉很有用的几个日常习惯

环境顺了之后，真正影响效率的是一些细节习惯。我平时会在每个 LaTeX 项目里单独用 Git 建仓库，只把 .tex、.bib、图片原文件这些真正需要版本管理的内容入库。中间产物（.aux、.log、.out 这些）是编译过程中自动生成的，应该全部排除掉，不让它们污染版本库。

文件的存放路径我坚持不用中文名，也尽量避免空格。早期的 LaTeX 工具对中文路径支持时好时坏，即便现在主流发行版已经支持，我依然习惯用英文路径，因为它能让各种工具少出幺蛾子。这个习惯在跨平台协作时尤其重要，同一个项目在 Windows、macOS、Linux 上打开，行为不会因为路径解析而不同。

遇到宏包功能和编译问题，我建议自己去查宏包的官方文档，而不是在论坛里做伸手党。LaTeX 相关技术资料相当完整，宏包的使用说明通常就是一份 PDF 文档。学会看文档、学会读日志，这两项技能的投资回报率非常高。

还有一个小经验：遇到不明错误时，先删掉所有辅助文件，然后重新编译。很多“诡异”的问题，比如引用符号显示异常、目录页码错乱、PDF 页数不对，都是旧辅助文件残留引起的。清理后如果能正常编译，那基本就和代码逻辑无关了。

5.3 最后再分享一点个人体会

从一开始连 xelatex 和 pdflatex 都分不清，到后来能在 VS Code 里一口气写好几十页带目录、参考文献、公式编号的完整文档，中间确实踩了不少坑。回过头看，真正让这套环境好用的关键不是某个特别牛的参数或插件，而是把“编译方式固定下来”：固定用 xelatex、固定用 latexmk、固定项目结构。

这套配置我不止在一个场景里用过。写技术报告、写期刊投稿、甚至写一些图文混排的操作手册，都是同一套流程。只要把这套基础环境打牢，之后不管遇到什么样的 LaTeX 模板，你都可以把精力全部放在内容本身，而不是被编译环境反复折腾。如果你刚开始配环境，记得一定先把最小文档跑通，再慢慢加宏包和样式。基础流程稳定了，LaTeX 会变成你写长篇技术文档时最可靠的工具。