企业官网建设流程全解析

1. 为什么最终选了这三件套

写 LaTeX 的人应该都折腾过工具链，我也不例外。早期用那种集成度很高的编辑器，虽然开箱即用，但代码补全弱、主题难看、想要个自定义宏都要翻配置；后来换过 Web 编译方案，网络一波动就卡半天，离线完全没法干活。折腾一圈下来，最后固定在了“VS Code + LaTeX + SumatraPDF”这套组合上，一用就是好几年。

先在开头把话说明白：VS Code 负责源码编辑，LaTeX Workshop 扩展负责接管编译、语法检查、正反向搜索这些脏活，SumatraPDF 负责渲染 PDF 并且和源码精准互跳。这个组合对新手非常友好，刚入门的同学可以照着配置一步步来；对老手也很值得参考，因为里面很多细节和坑，不是文档里一眼能看到的。

1.1 三个角色，各司其职

很多工具链的问题是“每一个环节都凑合”，结果组装起来非常别扭。这套方案好就好在三个组件各管一块，职责边界非常清楚：

• VS Code 只当编辑器，负责写.tex源文件、管理工程结构、用 Git 做版本控制，它不需要内置 PDF 渲染器，也不需要内置 LaTeX 编译器。
• LaTeX Workshop 扩展是中间层，它监听保存事件、调用 TeX 发行版里的编译程序、把生成日志解析成可读的错误提示，并提供 SyncTeX 同步命令。
• SumatraPDF 只干预览这一件事，轻量、启动快、对 PDF 大文档的渲染流畅，最关键的是它原生支持 SyncTeX 正向和反向搜索协议。

分段负责的好处是每个环节都能换成自己更喜欢的工具，不必被一家厂商锁定。比如编辑器换成别的，只要反向搜索命令支持，整个流程依然成立。这种“松散耦合”的思路，恰恰是维护成本最低的。

1.2 对比其他方案的取舍

市面上不是没有现成的“全家桶”。比如 TeXwriter 之类的商业编辑器，或某大型 IDE 自带的 LaTeX 插件，确实也能完成编译预览。但我个人不推荐把它们作为主力，原因有三点：

第一，编辑器定制能力弱。写论文时经常要做代码块高亮、表格片段、图表片段管理，通用编辑器能配合各种扩展生态，而专用 LaTeX 编辑器在这方面普遍保守。

第二，预览器不够轻。某些全家桶把 PDF 预览直接塞进集成界面，内存占用高，大型文档翻页卡顿明显。SumatraPDF 只有几十 MB 级别内存占用，一个几百页的学位论文打开几乎无感知。

第三，同步体验不一致。正反向搜索看起来是小事，实际用起来差距很大。SumatraPDF 的双击反向搜索稳定到可以“闭眼用”，而很多自带预览器的同步只能精确到页面，不能精确到行。

这也就是为什么我把“联合使用”作为关键点来写——单独用任何一个都不新鲜，新鲜的是把它们成功地“接”在一起。

2. 环境准备与安装

在配置之前，先确认三样东西装好：TeX 发行版、VS Code、SumatraPDF。顺序建议先装 TeX 发行版，再装 VS Code，最后装 SumatraPDF，因为 LaTeX Workshop 在首次启动时会探测系统里的编译程序，先把编译环境准备好，能少踩一个坑。

2.1 TeX 发行版怎么选

Windows 上主流的 TeX 发行版是 TeX Live 和 MiKTeX，选哪个取决于你的使用场景。

• TeX Live：宏包仓库最全，每年发布新版，跨平台一致性好。缺点是企业级安装体积大，完整安装可能到 7GB 以上，但你可以只装部分宏包集合。我自己的机器上一直用 TeX Live，因为长期写论文，各种宏包迟早要装。
• MiKTeX：优点是“按需自动安装宏包”，编译时如果缺某个包，它会提示并自动下载。初次体验非常友好，适合只在电脑上偶尔处理 LaTeX 文档，不想一次性装十几个 G 的用户。缺点是同一环境下换机器时，宏包版本可能不一致。

安装时有个容易忽略的选项：是否把二进制目录加入系统 PATH。厂商默认可能提示，但如果不加，LaTeX Workshop 找不到pdflatex或xelatex命令，后面所有的编译动作都会失败。装完建议打开终端敲一句：

xelatex --version

能正常输出版本，说明 PATH 没问题。

另一点注意：国内环境下 TeX Live 官方仓库下载可能慢，安装时可以使用镜像站点，具体地址可以在工具帮助里找到。这不是技术问题，但能省下大量等待时间。

2.2 安装 VS Code 与 LaTeX Workshop

VS Code 装好后，直接在扩展面板搜索 LaTeX Workshop，安装量最高的那个就是，作者是 James 的年份代码，但不用记，认准标识即可。安装后用快捷键Ctrl+Shift+P打开命令面板，输入LaTeX Workshop: View能看到相关命令，说明扩展已生效。

LaTeX Workshop 不依赖任何额外 Python 环境或 Node.js，它是纯扩展，插件内部直接调用外部编译命令，所以你的 TeX 发行版才是真正的重头戏。建议同时装两个辅助扩展：

• LaTeX Language Support或类似语法工具，提供更完整的语法高亮和自动补全。
• LTeX之类的拼写与语法检查，对英文论文写作特别有用。

不过辅助扩展会多占用一些资源，机器较老的话，第一个扩展就够用了。

2.3 安装 SumatraPDF 并验证反向搜索

SumatraPDF 是绿色软件，官方页面下载便携版即可，解压到固定目录比如D:\SumatraPDF\SumatraPDF.exe。它不需要安装，但需要记住路径，后面配置 LaTeX Workshop 要写完整路径。

装完先手工验证一下：用任意 LaTeX 编译器生成一个含 SyncTeX 信息的 PDF，在 SumatraPDF 里打开，确认能显示页面。主要目的是排除多软件抢占 PDF 文件句柄的问题。如果你之前装过其他 PDF 阅读器，可能把它们列为默认应用，这不影响使用，但会干扰外部调用时的打开行为。建议把.pdf的默认打开方式临时保持为 SumatraPDF，或者干脆不在文件资源管理器里双击 PDF，而是通过 LaTeX Workshop 的按钮唤起。

验证反向搜索之前，还需要启动 VS Code 时加一个命令行参数，让外部调用能复用现有窗口。后面配置部分我会说明完整写法，这里先把环境准备好。

3. 核心配置逐项拆解

这一部分是整套方案的灵魂。很多人配置失败，不是因为步骤少，而是不知道 JSON 里每一项到底管什么。下面我按模块拆开讲，你复制配置时能明白逻辑，而不是盲抄。

3.1 让预览器指向 SumatraPDF

LaTeX Workshop 默认的预览器是内置的 Tab 预览，也就是在 VS Code 内部打开一个 PDF 标签页。这个内置预览大多数时候够用，但它不支持个别精细的 PDF 特性，而且同步跳转的体验不如下载外部阅读器。要切换到外部预览，需要修改扩展设置中的三项：

"latex-workshop.view.pdf.viewer": "external", "latex-workshop.view.pdf.external.viewer.command": "D:/SumatraPDF/SumatraPDF.exe", "latex-workshop.view.pdf.external.viewer.args": [ "-forward-search", "%TEX%", "%LINE%", "%PDF%" ]

viewer.command的值很简单，就是 SumatraPDF 的绝对路径，注意 Windows 下正斜杠或双反斜杠都行，反斜杠在 JSON 里需要转义，所以我习惯用D:/SumatraPDF/SumatraPDF.exe。

args里的三个占位符非常关键：%TEX%是当前 LaTeX 源文件路径，%LINE%是要跳转到的行号，%PDF%是编译生成的 PDF 路径。-forward-search是 SumatraPDF 自己的参数，意思是“收到这些信息后直接翻到对应页面并高亮”。如果这里填错或少填，正向搜索就会变成“打开 PDF 但不跳转”。

注意：第一次在 SumatraPDF 中执行正向搜索时，可能会弹出一个提示框，问是否允许来自外部程序的“命令行控制”。这是 SumtraPDF 的安全机制，勾选“信任来自该程序的调用”并确定即可，否则后续跳转都会被拦截。

3.2 编译方案 recipes 和 tools

LaTeX Workshop 把编译流程抽象成两层：最底层叫tool，是具体的编译命令，比如pdflatex、xelatex、latexmk；上面一层叫recipe，是一组 tool 的组合，可以带latexmk然后执行bibtex，再执行两遍pdflatex。

默认配置里已经内置了几组 recipe，比如pdflatex -> bibtex -> pdflatex x2。但如果你使用中文文档，需要换latexmk配合xelatex引擎。我常用的三段配置如下：

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

为什么要专门说-synctex=1？因为正向反向搜索靠的就是 SyncTeX 文件。如果编译时不开这个开关，生成的.synctex.gz文件不存在，后面所有跳转都无效。-interaction=nonstopmode的作用是让编译器遇到错误时不暂停等待输入，否则某些交互式错误会让整个构建过程卡在半路，新手尤其容易踩中。

%DOC%是 LaTeX Workshop 的内置占位符，代表当前文档去除扩展名后的路径。注意它不会自动加.tex，但编译器和扩展配合时能正确解析。

配置好 recipe 后，需要把默认 recipe 指定为第一个。在设置里找latex-workshop.latex.recipe.default，填first或指定 recipe 名。这样每次保存后，自动构建就会走你真正想要的那条链。

3.3 反向搜索命令的完整写法

SumatraPDF 的反向搜索需要在它自己的设置界面里配，不是在 VS Code 里。打开 SumatraPDF，进入“设置 → 选项”，在最下方的“反向搜索命令行”文本框里填入内容。不同 VS Code 版本的路径写法略有差异，但下面这个写法在我用过的多个版本上都是稳定的：

"D:/Microsoft VS Code/Code.exe" --reuse-window --command "latex-workshop.synctex.forward"

注意几个细节。--reuse-window保证调用不会弹出一个全新的 VS Code 窗口，而是聚焦到现有窗口；--command后面的值必须是 LaTeX Workshop 注册的命令名，随意改名字会失效。这里没有传%f:%l，因为 LaTeX Workshop 的处理逻辑不是靠文件名和行号直接跳，而是由它接管后再发起一次反向同步解析。如果你遇到双击 PDF 毫无反应，优先检查这一行命令路径是否正确，其次检查 VS Code 是否真的启动了 LaTeX Workshop 扩展。

有的老教程会让你填：

"code" -g "%f:%l"

这种写法在旧版本里有效，它走的是 VS Code 原生“文件跳转到行”能力，并不依赖 LaTeX Workshop。新版 VS Code 里code命令如果没有加入系统 PATH，会提示找不到命令。所以更稳妥的做法是把完整路径写出来，并用--command "latex-workshop.synctex.forward"。

配置完成后，在 SumatraPDF 的 PDF 上双击，应当自动跳到源码对应行，并且 VS Code 会短暂高亮那一行。如果没反应，回到第 5 节看排查方法。

4. 从零实操：一套完整走通流程

光给配置不给演示，总觉得不踏实。这一节我从一个全新的空目录开始，手把手走一遍完整流程。你只需要照顺序操作，就能体会整套工具链的爽感。

4.1 创建最小文档并完成首次编译

先新建一个文件夹，用 VS Code 打开该文件夹，然后新建main.tex，写入下面这份最小内容：

\documentclass{article} \usepackage{ctex} \begin{document} 你好，LaTeX。 \end{document}

按下Ctrl+S保存，如果你设置了自动构建，右侧状态栏会出现一个旋转图标，控制台输出 xelatex 运行日志。如果自动构建没有触发，按Ctrl+Alt+B手动触发。

首次编译完成后，左侧文件树会多出main.pdf，同时可能出现.aux、.log、.synctex.gz等辅助文件。这些辅助文件不需要提交到 Git，后面我会讲怎么自动清理。

看到main.pdf生成后，按下Ctrl+Alt+V，LaTeX Workshop 会把这份 PDF 交给外部查看器。如果刚才的 external viewer 配置没问题，SumatraPDF 会立即打开并显示第一页。

新手容易在第一步就卡住：自动构建没反应。原因十有八九是 PATH 里没有 xelatex，或者 recipe 里指定了不存在的 tool。在终端敲xelatex --version，如果命令不存在，说明发行版没装好或者 PATH 没配置；如果命令存在，再看 VS Code 输出面板里的错误日志，它会明确说“recipe not found”还是“tool not found”。

4.2 实测正反向搜索与同步定位

PDF 打开后，把窗口摆成左右分屏，左边 VS Code，右边 SumatraPDF。在 VS Code 源码第 3 行（也就是你好，LaTeX。所在行）按下Ctrl+Alt+J，观察 SumatraPDF 瞬间跳转到对应位置，并出现一个浅色高亮矩形，这就是该行内容在 PDF 里的渲染位置。

反过来，在 SumatraPDF 里双击你好，LaTeX。这一行文字，焦点回到 VS Code，光标精准定位到main.tex的第 3 行，同时该行底色短暂高亮。到这一步，整套联动闭环已经打通。

我经常遇到一种情况：同步能跳到页面，但位置偏了半行，比如源码第 50 行跳到 PDF 第 3 页，光标对不准实际行。这通常不是配置问题，而是编译时-synctex=1没有生效，或者编辑器里存在“源码行偏移”，比如顶部有太多注释。解决办法是每次修改源码后重新编译一次，SyncTeX 数据是编译时生成的，不重新编译它不会自动更新。

4.3 多文件工程里怎么处理 root 文件

实际写论文不会把所有内容塞在一个文件里，通常会有一个main.tex作为主文档，然后用\input{chapters/chapter1.tex}引入各个章节。这时 LaTeX Workshop 有一个非常智能但有时也招人烦的“检测当前文档主文件”机制。

如果你在chapter1.tex里保存，而它没有任何标记指明主文档是谁，扩展可能尝试从当前文件开始编译，结果当然是失败，因为chapter1.tex可能不是一个完整文档。解决办法是在每个子文件的顶部加上一行魔法注释：

% !TEX root = ../main.tex

这行注释不是 LaTeX 语法的一部分，是 LaTeX Workshop 和很多 LaTeX 编辑器共同支持的约定。它明确告诉扩展“你在这个文件里操作时，用哪个文件作为编译入口”。多文件项目里，这行注释能省下大量切换主文件的麻烦。

如果项目同时有多个.tex文件都带着% !TEX root = main.tex，没问题，扩展会按 root 标识正确编译；只有当所有文件都没有 root 标识，并且目录下有多个可编译主文件时，它才会每次弹提示让你选。所以我的习惯是：每个子文件第一行都写上 root 关联。

5. 常见问题排查与避坑实录

配置一套东西，最怕的不是配不出来，而是配好之后不知为何又坏了。这一节我列几个高频问题，都是我自己或身边同事踩过的真实案例。

5.1 编译成功但 PDF 预览打开的是旧版本

这种问题非常隐蔽。表现是：日志显示“Output written on main.pdf”，生成时间也是最新的，但 SumatraPDF 显示的依然是旧内容，或者页数不对。

原因通常是 SumatraPDF 打开了旧文件后，没有自动重载。它默认会在文件变更后自动刷新，但如果文件被其他程序短暂锁定，或者预览器在编译完成前就读取了文件，可能会错过刷新信号。

处理办法分两级。临时做法是在 SumatraPDF 里按Ctrl+R手动重载；长久的做法是在 LaTeX Workshop 的 external viewer 配置里，确认args的顺序是-forward-search %TEX% %LINE% %PDF%，不能少参数。另外，有一种情况是 TeX 发行版改成了输出到临时目录，比如配置了-output-directory=build，但 LaTeX Workshop 默认找的是主目录里的 PDF。如果用了输出目录，需要同步配置latex-workshop.latex.outDir，否则预览程序会找错文件。

5.2 反向搜索失效的各种原因

双击 PDF 不跳回源码，这个问题的排查顺序非常固定。

第一步检查 SumatraPDF 是否弹出了“允许外部调用”的窗口。有的系统更新后，安全沙箱会重新询问信任规则，你没点确认，反向搜索就会被静默拦截。

第二步检查设置中的命令行路径是否被系统更新改掉。VS Code 升级后可能换安装路径，特别是从系统安装版本换成用户安装版时，Code.exe的位置会变化，旧路径就会失效。

第三步检查 LaTeX Workshop 是否真的在运行。把 VS Code 完全退出（不是关闭窗口，而是退出进程），再重启，然后点击一个.tex文件，看看状态栏有没有 LaTeX Workshop 的状态。如果没有，说明扩展并没有激活。

第四步检查 PDF 文件本身有没有携带 SyncTeX 信息。在 SumatraPDF 中按F6打开书签/结构面板，如果看到“SyncTeX”相关的菜单灰显，说明编译参数里没有开启同步信息。回到 recipe 里确认-synctex=1。

以上四步按顺序走完，九成以上的反向搜索问题都能定位。剩下的一成，一般是.synctex.gz文件损坏或版本不匹配，删掉所有辅助文件后重新编译一遍即可。

5.3 中文文档编译失败或字体异常

中文用户最常遇到的是编译报错或输出 PDF 中文变成空白方块。这里有一个基本认知要先建立起来：默认情况下pdflatex不处理中文，需要用支持 Unicode 的引擎。所以中文文档的 recipe 必须走xelatex，并且文档里要加载ctex宏包。

\documentclass{ctexart} % 或 \documentclass{article} \usepackage{ctex}

ctexart文档类会自动处理中文字体配置，在大多数发行版里不用额外设置。如果使用article + ctex宏包，注意加载顺序，别在\usepackage{ctex}之后又用CJK或fontspec强行替换字体，容易冲突。

有几种症状需要区分：

• 报错Missing font或.pfb文件缺失，说明字体工具不完整，先重装完整版 TeX Live 再试。
• 编译成功但中文显示为空白方块，大概率是缺中文字体，检查系统是否安装了中文字体。
• 编译时某宏包报错说“not found”，比如ctex.sty not found，说明发行版不完整，需要安装补齐宏包。TeX Live 用户可以用 tlmgr 安装缺失宏包。

我自己的建议是：不管写中文还是英文，默认都配一个latexmk -xelatex的 recipe。中文没问题，英文也没问题，只有极少数特殊情况才需要退回 pdflatex，比如期刊模板强制要求传统引擎。

6. 提升日常写作体验的几个细节

配置打通只是开始，真正舒服的写作体验，还要靠几个小技巧。这些技巧单看都不复杂，组合起来却能大幅减少你从“想写东西”到“看到 PDF”之间的摩擦。

6.1 魔法注释：控制编译程序和主文档

前面讲到% !TEX root用于多文件主文档识别。还有另一个魔法注释值得掌握：% !TEX program = xelatex。它会把当前文件硬指定为 xelatex 编译，优先级高于配置里的默认 recipe。

% !TEX program = xelatex % !TEX root = ../main.tex

放在任何一个子文件顶部，LaTeX Workshop 就会自动识别并切换编译方案。这个注释对我特别有用：有时一个项目里既有中文主文档，又有一两个英文测试文件，后者需要走 pdflatex，用魔法注释就不会互相干扰。

注意魔法注释必须出现在文件头部，一般要求是前几行内。如果放在正文中间，扩展会忽略它。

6.2 设置自动构建策略，别让编译频繁打断思路

默认情况下 LaTeX Workshop 可能在保存时自动编译。这听起来很高效，但实际上每次保存都触发一次完整 xelatex，对于大型文档来说，会频繁占用 CPU，并且日志刷屏。我更推荐手动构建，或者保存后延迟自动构建。

可以改成只在明确按键时构建：

"latex-workshop.latex.autoBuild.run": "never",

编译快捷键是Ctrl+Alt+B，预览是Ctrl+Alt+V，SyncTeX 是Ctrl+Alt+J。这三个快捷键是核心，记住它们，写作过程基本不需要鼠标。

如果你实在喜欢自动构建，可以折中一下，把latex-workshop.latex.autoBuild.interval调大，或者只在onSave时构建。不过从经验讲，手动构建能避免“改到一半就被编译结果打断”的体验，反而更专注。

6.3 辅助文件清理与 Git 仓库管理

LaTeX 编译会产生一堆辅助文件：.aux、.log、.toc、.out、.synctex.gz等。这些文件对最终 PDF 无关，提交到 Git 只会制造大量冲突。合理的做法是忽略它们，并在需要时一键清理。

LaTeX Workshop 已经内置了清理命令，可以直接用Ctrl+Alt+P打开命令面板后搜索LaTeX Workshop: Clean auxiliary files。也可以在配置里自定义清理目录：

"latex-workshop.latex.clean.fileTypes": [ "*.aux", "*.log", "*.toc", "*.out", "*.fls", "*.fdb_latexmk", "*.synctex.gz" ]

如果你的项目使用build目录存放中间文件，清理前要确认outDir配置一致，别把main.pdf也当辅助文件删了。另外我建议在项目根目录放一个.gitignore，把辅助文件模式加进去，这样即使误操作清理，也不会把版本库搞脏。

6.4 代码片段和格式化技巧

VS Code 本身支持用户代码片段，LaTeX 写作也能受益。比如定义一个figure片段，输入fig再按 Tab 就能生成一段完整图片环境模板。这个功能可以极大减少重复输入。

用户代码片段配置文件在“文件 → 首选项 → 配置用户代码片段 → 新建全局代码片段文件”，选 latex 语言即可。一个简单的图片模板如下：

"Figure": { "prefix": "fig", "body": [ "\\begin{figure}[htbp]", " \\centering", " \\includegraphics[width=0.8\\linewidth]{$1}", " \\caption{$2}", " \\label{$3}", "\\end{figure}", "" ], "description": "插入 figure 环境" }

写完后在.tex文件里输入fig，你会看到补全提示，Tab 即可展开。这个模板面向我自己的习惯，你可以随意替换成表格、公式、代码块等常用结构。

这类提高输入效率的小优化虽然和“联调”关系不大，但一旦用顺了，你就再也回不到手打全套环境标签的老方法。

写在最后的一点真心话

从最早的编辑器，到各种商业软件，再到现在这一套 VS Code + LaTeX + SumatraPDF 的组合，我最大的体会就是：工具链好不好用，不在于每个部件多高级，而在于它们之间的衔接是不是自然。SyncTeX 的流畅跳转，让“改源码 → 看效果 → 改源码”这个循环缩短到两秒以内，这是我坚持这套方案最核心的理由。

如果你是一名刚接触 LaTeX 的新手，建议不要急着把所有配置都玩出花样。先把最简单的一篇中文文档编译出来，再一步步加上正反向搜索、多文件管理、自动清理。每多加一层，你都知道它解决什么问题，这样就算将来环境崩了，也能很快定位原因。

最后分享一个我自己用出来的小技巧：在 SumatraPDF 的分栏模式下写双栏论文，可以把窗口拉宽，按快捷键切换单页连续模式，对检查跨页表格特别友好。编译、预览、跳转、修改，这一整套动作熟练之后，你会觉得写 LaTeX 其实没那么痛苦，甚至可以是一种享受。