企业官网建设流程全解析

做 LaTeX 这件事，坑从来不在语法上，而在于"环境"这两个字。TeXLive 装完、VSCode 配好、PDF 能顺顺当当预览出来——这三句话念起来跟报菜名一样简单，但真到自己动手，十个初学者里六七个会卡在中间：要么编译时提示找不到命令，要么中文文档一编译满屏方块，要么预览窗口和源码对不上位置，点一下跳转没反应。我这套 TeXLive 加 VSCode 的组合用了好几年，从 Windows 笔记本一路折腾到远程服务器，预览方式也把内置标签页、外部阅读器、浏览器三种都轮流用过，踩过的坑足够攒出一份清单。下面就把整套链路拆开讲，重点放在"为什么这样配"和"哪种预览方式适合哪种场景"，让你少走我当年绕的那些弯路。

1. 为什么这套组合值得折腾：TeXLive 与 VSCode 各自的角色分工

很多人一开始会把这件事想成一件事，其实它是三件事拼起来的：排版引擎、编辑器、预览器。三者各干各的，通过文件系统和命令行松耦合地连在一起。搞不清这个分工，配置的时候就会到处乱试，把编辑器的问题当成引擎的问题，把预览的问题当成编译的问题。

1.1 两个组件各自的职责边界

TeXLive 是真正干活的那个。它是一个完整的发行版，里面装着编译器（引擎）、成千上万个宏包、字体、参考文献处理工具、索引工具，以及 tlmgr 这个包管理器。你写的 .tex 文件最终能变成 PDF，靠的全是 TeXLive 里的东西。它跟编辑器没有半点关系，你完全可以用记事本写 .tex，然后命令行敲 xelatex 编译，一样出 PDF。

VSCode 的作用则简单得多——它是个写字的地方，外加一个"跑命令的遥控器"。它本身不会排版，装上 LaTeX Workshop 插件之后，插件做的事是：检测到你保存了 .tex 文件，去调用 TeXLive 提供的命令行工具（比如 xelatex、latexmk），再把生成的 PDF 显示在某个地方。所以当编译报错说"command not found"，问题在 TeXLive 的路径配置；当提示"未找到 PDF"，问题多半在预览器或输出目录。把这条边界记牢，排错能省一半时间。

1.2 什么项目适合这套组合，什么项目不适合

说句实在话，LaTeX 不是万能的。如果有人只是写一篇两页的通知，或者需要严格按某个 Word 模板交稿、还要走审阅批注流程，那这套组合反而给自己添堵。它的真正优势场景是：文档里公式密集、交叉引用极多、参考文献上百条、章节结构常年迭代、需要版本管理（.tex 是纯文本，Git 友好到极致）。这类文档用 Word 维护，后期改一个符号就要动好几处，而 LaTeX 靠标签和自动编号，改起来几乎是零成本。

我自己的判断标准很简单：如果这份文档未来还要改三次以上，而且是技术类内容，就上 LaTeX；如果是一次性交付且格式由别人定死，就用顺手的工具。别为了用而用。

1.3 一条最小可用链路长什么样

一条能跑通的最小链路是：.tex源文件经过编辑器触发命令，调用 TeXLive 的编译工具链，产出一个带 SyncTeX 信息的.pdf，然后被某个预览器打开，预览器再通过 SyncTeX 把点击位置映射回源码行号。这四步里任何一环断了，体验都会崩。后面几节基本就是围绕"怎么保证这四步都稳"来展开的。

2. TeXLive 安装：中文用户名是最大的隐形地雷

先讲安装，因为这是最劝退的一步，也是最容易被忽略的一步。很多教程只写"下载、下一步、下一步、完成"，但真按这个走，偏偏有人就装不上，而且报的错莫名其妙，让你以为是网络问题或者磁盘问题。

2.1 安装方式选择：在线安装器、ISO 与镜像站的取舍

Windows 上主流有三种装法：在线安装器（install-tl-windows.exe）、完整 ISO 镜像（几个 G，下载后挂载安装）、以及借助国内镜像站加速。在线安装器体积小，但安装过程要持续联网拉包，对网络稳定性要求高，中途断一次就得重来；ISO 镜像一次下载到位，装的时候完全离线，适合网络环境一般或者需要给多台机器部署的情况。

我的建议是：如果只是自己一台机器用，网络还行，就选在线安装器并换成国内镜像源，速度会快很多；如果网络时好时坏，或者要给实验室、机房的机器批量装，直接下 ISO，省心。镜像站的关键是安装界面里能切换 repository，把默认源换成离你近的即可，这个设置项藏得比较深，在安装器的高级选项里。

2.2 中文用户名为什么会把安装卡死

这是我认为最值得单独拎出来讲的一点。Windows 上如果账户名是中文，用户目录路径就会带中文，比如C:\Users\张三。而 TeXLive 的安装脚本内部用了 Perl，很多临时文件、日志、配置默认写在用户目录下，一旦路径里含有非 ASCII 字符，某些环节就会直接抛错或者静默失败——表现往往是安装进度条卡在某一步不动，或者装完了但 tlmgr 一运行就报路径相关的错误。

更麻烦的是，这个问题不会很直白地告诉你"你的用户名是中文"。它可能报的是一堆看不懂的 Perl 错误、找不到某个临时文件、编码转换失败之类，初学者很难第一时间联想到账户名。我当年就是卡在这里，重装了三遍才反应过来。

2.3 三种绕开中文路径的实操方案

方案一，也是最彻底的：新建一个纯英文名的本地账户，比如texuser，在这个账户里安装和使用 TeXLive。缺点是日常要切换账户，但对 Lab 环境、公用机器来说最省事。

方案二，临时重定向临时目录。不换账户，但在运行安装器之前，把临时目录指到一个纯英文路径上：

mkdir C:\texlive-tmp set TEMP=C:\texlive-tmp set TMP=C:\texlive-tmp install-tl-windows.bat

这样安装脚本写临时文件时就不会碰到中文路径。注意这个设置只在当前命令行窗口有效，关掉就恢复，所以更适合用批处理脚本一次性执行。

方案三，安装完成后修正 TeXLive 自己的用户目录。即使安装过关了，后续 tlmgr 更新、texhash 刷新字体缓存这些操作，默认还是把用户级配置写在%USERPROFILE%下。手动加三个环境变量，把它们挪到英文路径：

这三个变量一加，tlmgr 和字体缓存刷新基本就不会再因为用户名中文而翻车。我个人是三套方案叠加用的：换英文账户最保险，配合环境变量基本一劳永逸。

2.4 装完之后必须校验的三件事

装完别急着写文档，先花两分钟验一下。第一，命令行敲tex --version和xelatex --version，能打出年份版本号说明 PATH 配好了；如果提示不是内部或外部命令，说明安装目录的 bin 没进 PATH，手动加一下（形如C:\texlive\2024\bin\windows）。第二，敲tlmgr --version，确认包管理器能跑，这是后期补装宏包的命脉。第三，写一个最小的中文测试文件编译一遍，看中文有没有变方块，这一步能提前暴露字体和编码问题，比写了一半才发现强太多。

3. VSCode 侧配置：LaTeX Workshop 里真正要改的几项

TeXLive 装好之后，编辑器的配置其实没多少工作量，但每一项都容易配错，尤其是直接复制网上配置的时候。核心插件就一个：LaTeX Workshop。

3.1 插件安装与 settings.json 的正确写法

在扩展面板里搜 LaTeX Workshop 装上就行。它的配置全部写在 VSCode 的 settings.json 里。这里有个新手常踩的坑：settings.json 是 JSONC 格式（允许注释和尾逗号），但如果你从别处复制配置时多留了一个尾逗号，或者注释符号用错了，整个配置会静默失效或者报解析错误，编译行为就完全不按你写的来。改完配置记得看一眼有没有黄色波浪线提示。

还有一点，LaTeX Workshop 更新比较勤，有些配置项名会变。遇到"配置了却没生效"，先去插件文档确认项名是否还叫这个，比在社区里到处问快得多。

3.2 编译工具链（tools）与配方（recipes）的区别

这是理解配置的关键。tools 是"单个命令"，recipes 是"命令的执行顺序"。比如：

"latex-workshop.latex.tools": [ { "name": "xelatex", "command": "xelatex", "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%"] }, { "name": "bibtex", "command": "bibtex", "args": ["%DOCFILE%"] } ], "latex-workshop.latex.recipes": [ { "name": "xelatex x2", "tools": ["xelatex", "xelatex"] }, { "name": "xelatex bibtex x2", "tools": ["xelatex", "bibtex", "xelatex", "xelatex"] } ]

-synctex=1是预览跳转的前提，-interaction=nonstopmode让编译遇错不卡在交互提示，-file-line-error让报错行能直接点击跳转。这几个参数不是可选项，是体验的底线。而 recipes 写成多轮，是因为交叉引用和目录要靠多趟编译才能收敛——第一趟收集标签，第二趟才把编号填进去。

3.3 中文文档为什么必须换成 xelatex

pdflatex 对中文的支持一直很别扭，要么用 CJK 宏包配一堆编码设置，要么字体找不到。xelatex 原生支持 UTF-8 和系统字体，是现在中文排版的主流引擎。所以中文项目里，配方默认工具要设成 xelatex，编译命令也要用 xelatex。判断标准很直接：如果文档里出现\documentclass{ctexart}或\usepackage{ctex}，就老老实实用 xelatex，别用 pdflatex 硬扛。

3.4 自动编译的触发时机与性能取舍

LaTeX Workshop 提供latex-workshop.latex.autoBuild.run选项，可以设成 onFileChange（改一下就编）、onSave（保存才编）、never（手动编）。文档小的时候 onFileChange 很爽，边写边看；但项目一大，每敲一个字符就触发一次全量编译，编辑器会明显卡顿，风扇狂转。我自己的习惯是小文档用 onSave，大文档直接 never，靠快捷键手动触发，反而更可控、更省电。

4. 三种预览方式的实际差异：内置标签页、外部阅读器、浏览器

预览这块是这套组合里最容易被忽略、但对体验影响最大的一环。同一个 .tex，换一种预览方式，感受可能天差地别。

4.1 内置标签页预览：零配置但有软肋

LaTeX Workshop 自带一个 PDF 预览标签页，配置项是"latex-workshop.view.pdf.viewer": "tab"。优点是不用装任何额外阅读器，编译完自动在旁边开一个标签展示 PDF，跨平台一致，适合 Quick Start。缺点是渲染器功能偏弱：大文档翻页会顿，标注和批注基本别想，缩放和连续滚动的体验比不上专业阅读器。而且它的正反向跳转虽然支持，但对复杂项目偶尔会错位。

如果你只是写短文档、做草稿，内置标签页完全够用，省心。我最初就是用这个跑通的，先让它能出 PDF，建立信心，再谈优化。

4.2 SumatraPDF 外部预览：正反向搜索最顺的组合

Windows 上想认真用，我强烈推荐 SumatraPDF 作为外部阅读器。它启动快、渲染顺、原生支持 SyncTeX 的反向搜索，是 LaTeX 圈子里的经典搭配。配置大致是这样：

"latex-workshop.view.pdf.viewer": "external", "latex-workshop.view.pdf.external.viewer.command": "C:/Program Files/SumatraPDF/SumatraPDF.exe", "latex-workshop.view.pdf.external.viewer.args": [ "-reuse-instance", "%PDF%" ]

然后在 SumatraPDF 里设置反向搜索命令，让它双击 PDF 时能跳回 VSCode 对应行。-reuse-instance是关键，保证每次编译复用同一个窗口，而不是开一堆新窗口。这套组合下，正向搜索（源码跳 PDF）和反向搜索（PDF 跳源码）都能用，写长文档时效率提升非常明显。

4.3 浏览器预览：适合长文档滚动但同步跳转弱

把 viewer 设成"browser"会启一个本地服务，用浏览器打开 PDF。好处是浏览器渲染引擎成熟，长文档滚动顺滑，缩放自由。缺点也明显：正反向同步跳转基本谈不上，而且总得开着浏览器，切来切去反而分散注意力。我一般只在需要仔细通读、反复上下滚动检查版式的时候用浏览器，日常写作还是外部阅读器。

4.4 三种方式对照表

选哪种没有标准答案，关键是知道每种方式的短板在哪。我通常是主用外部阅读器，偶尔切浏览器通读，内置标签页只在临时开个新文件试手时用。

5. SyncTeX 正反向跳转：配置写对了却跳不动的排查链路

SyncTeX 是这套组合里最让人又爱又恨的功能。配好了效率翻倍，配不好就是"我明明按教程写了，为什么点了没反应"。它出问题往往不是单一原因，而是一串链路里的某一环断了。

5.1 SyncTeX 的工作原理与前提

SyncTeX 的原理不复杂：编译时如果带上-synctex=1，引擎会额外生成一个.synctex.gz文件，里面记录了 PDF 里每个位置和源码行号、列号的对应关系。跳转时，预览器或插件读取这个文件做双向映射。所以第一个前提是编译参数必须有-synctex=1，第二个前提是输出目录里能找到这个.synctex.gz。很多人跳转失败，就是因为换了自定义输出目录（latex-workshop.latex.outDir），但预览器还在老地方找同步文件。

5.2 正向搜索失效的四个常见原因

正向搜索（从源码行跳到 PDF 对应位置）失效，我遇到过四种：一是编译命令漏了-synctex=1；二是手动清理过中间文件，把.synctex.gz删了；三是宏包或引擎版本不匹配，sync 信息没正确生成；四是用了自定义输出目录，同步文件位置没对上。排查顺序就按这个来：先确认编译参数，再确认文件存在，最后确认路径。快捷键一般是 Ctrl+Alt+J（源码到 PDF），Ctrl+Alt+K 或双击（PDF 回源码），不同版本可能略有差异。

5.3 反向搜索命令的写法与路径引号陷阱

反向搜索要在外部阅读器里配置跳回编辑器的命令。SumatraPDF 里的写法类似：

"C:\Users\你的用户名\AppData\Local\Programs\Microsoft VS Code\Code.exe" -g "%f:%l"

这里有两个大坑。第一个是路径里的空格，Program Files、Microsoft VS Code都带空格，整条命令的 exe 路径必须用引号包住，否则参数会被拆开。第二个是%f和%l这两个占位符，分别代表文件路径和行号，格式是%f:%l，中间那个冒号别写成别的符号。我当年就是少写了一对引号，折腾半天才发现问题。

5.4 多文件项目里的跳转错位

如果是分章节的多文件项目（用\input或\include拆分），SyncTeX 偶尔会把跳转位置指到主文件的对应行，而不是被包含的子文件里。这属于已知的边界情况。我的经验是尽量保证子文件和主文件都在同一工程目录下、相对路径清晰，能减少这类错位；实在错位了，手动翻一下也不费事，别在这上面钻牛角尖。

6. 中文排版链路：ctex、字体与参考文献的稳定搭配

中文文档是另一个独立的坑区。前面配置都对，中文一样可能出问题，因为字体和编码是另一套逻辑。

6.1 ctexart 与 ctex 宏包的选择

写中文文档，最简单的方式是直接用\documentclass[UTF8]{ctexart}，它对中文的默认配置最省心，标题、字体、间距都帮你调好了。如果文档需要更复杂的结构，就用 ctexbook 或 ctexrep。还有一种做法是保持 article 类不变，手动\usepackage{ctex}，灵活性更高，但配置量大一些。我的建议是新手直接用 ctexart 系列，先跑通再说，别一上来就手动配字体。

6.2 用系统字体还是打包字体

ctex 默认会调用系统里的中文字体（Windows 上一般是宋体、黑体这一类）。这在本地用没问题，但一旦换机器、换系统，字体可能就变了，甚至找不到报错。追求可移植性的项目，可以用\setCJKmainfont手动指定字体，或者干脆用打包进项目、随文档一起分发的字体文件。跨平台合作的项目尤其要注意这一点，否则同一份源码在别人机器上编译出来就是另一副样子。

6.3 参考文献与多轮编译顺序

带参考文献的中文文档，编译顺序马虎不得。用 BibTeX 的话，顺序是 xelatex、bibtex、xelatex、xelatex。用 biber（配合 biblatex）则是 xelatex、biber、xelatex、xelatex。第一趟让正文"认识"引用标签，文献工具处理 .bib，后两趟把引用编号和文献表填进去。这也是为什么前面 recipes 要写多轮——少跑一趟，参考文献就变成问号。我在这个点上吃过亏，一开始以为编译一次就够，结果引用的编号全是 [?]，找了半天才发现是轮次不够。

6.4 远程/容器环境下的字体缺失

如果是在 WSL 或远程服务器上跑这套组合，中文字体缺失是高频问题。服务器系统往往只装了最基本的字体，ctex 找不到中文字体直接报错。解决办法是把需要的字体文件拷到合适的位置，或者用随项目分发的字体，再刷新字体缓存。用 VSCode 连远程时，编辑器在本地、编译在远端，预览走 Remote 转发，这时候预览方式和本地不完全一样，需要额外注意同步和路径问题。

7. 我长期用下来总结的几条维护习惯

环境一旦跑通，日常维护其实不难，但有几个习惯能让它一直稳下去，省掉反复救火。

7.1 tlmgr 更新与回滚的节奏

TeXLive 的宏包会持续更新，但我建议不要看到更新就点。更新本身有风险——偶尔某个宏包的新版本会和你的文档不兼容，改了半天生成结果却变了。我的做法是：重要文档在交付前锁定现状，不做任何更新，等交付完再统一更新；更新前先确认当前工作没在赶进度。tlmgr 也支持回滚，真遇到某个宏包更新后出问题，可以单独回退到旧版本，不必重装整个发行版。

7.2 输出目录与中间文件的管理

编译会产生一堆中间文件（.aux、.log、.out、.toc 等），跟源码混在一起很乱，提交到版本库更是灾难。可以给 LaTeX Workshop 配一个独立的输出目录，或者用 .latexmkrc 指定。同时记得用.gitignore把 PDF 和中间文件排除掉，只提交源码。这套做法一旦养成，工程目录会清爽很多，找文件也快。

7.3 配置备份与跨机器迁移

最后一条最实用：把你调好的 settings.json 配置片段和那几个 TeXLive 环境变量单独保存一份，比如放到你自己的 dotfiles 仓库里。换机器的时候，五分钟就能把整套环境复刻出来，不用再从头踩一遍坑。我这些年换过好几台机器，就是靠这份备份，每次都是照抄配置、装个插件，环境就活了。

配置这东西，跑通一次之后就成了固定资产，接下来能安安心心写几年文档。第一次装的时候多花的那点时间，后面都会连本带利还给你。