TeXLive2020安装避坑：报错、镜像源与宏包配置

TeXLive2020安装这件事，说难不难，说简单也确实能把人卡上大半天。我在三台配置完全不同的机器上装过这套环境——一台是老笔记本上的机械硬盘、一台是刚配的开发机、还有一台是同事装了半截放弃甩给我的办公电脑，三次遇到的报错几乎不重样。TeXLive 本身是一套相当完整的发行版，装完之后宏包齐全、开箱能用，这也是很多人宁愿忍受几个G的下载量也要选它的原因；但它毕竟是一套从 Unix 世界移植过来的工具链，安装器用 Perl 写的，对 Windows 环境里那些"中国特色"路径、杀软拦截、权限限制的容忍度并不高。

这篇内容我打算把安装前该排的雷、安装包下载和镜像选择、安装器跑到一半崩掉的几种典型报错、装完之后的校验和编辑器配置、以及后面写文档时的宏包与字体问题，全部按我实际处理过的顺序讲一遍。适合第一次接触 TeXLive 的新手，也适合装到一半报错卡住、想找具体原因的老用户。我尽量不写那种"照着官网文档念一遍"的东西，重点放在报错背后的原因和可以直接抄的操作上。

1. 安装前不排雷，后面全是坑

TeXLive 的安装器有个特点：它在正式开始复制文件之前，会先跑一段 Perl 脚本做环境探测和方案计算，这一步出问题的概率比你想象的高得多。而一旦这一步挂了，报错信息往往非常模糊，你根本不知道是路径的问题、权限的问题还是网络的问题。所以与其装到一半再回头折腾，不如先把环境理干净。

1.1 三种安装路线，先想清楚自己要走哪条

TeXLive2020 在 Windows 上有三种比较主流的安装路径，它们对应的时间成本、容错能力和适用场景差别很大，很多人卡住其实是因为一开始就选错了路线。

我个人的建议是：如果你不是非得追最新宏包，直接走 ISO 路线。原因很实际——网络安装模式下，安装器要从镜像源逐个拉取几千个包，中间任何一个包超时都会让整个流程中断，而它的断点续传能力很有限。ISO 是一次性的文件下载，断了用下载器接着下就行，装的时候从本地读，速度稳定得多。

在线安装的命令行方式是：

install-tl-windows.bat -no-gui -repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet

加-no-gui走的是纯命令行交互模式，看起来朴素，但比图形界面少一层 Tk 依赖，出问题的概率反而更低。图形界面在部分高 DPI 屏幕上还会出现控件错位、按钮点不到的情况，命令行模式没有这个烦恼。

1.2 装之前必须检查的五件事

这五条是我踩坑之后总结出来的检查清单，任何一条不满足，后面都可能变成一次莫名其妙的失败。

第一，确认你的 Windows 用户目录路径里没有中文。在命令行里敲echo %USERPROFILE%，如果输出类似C:\Users\张三，那就要注意了。TeXLive 的安装器、tlmgr、以及部分宏包的构建脚本在处理非 ASCII 路径时会直接抛异常，报错信息通常只是一句perl backend相关的内容，看不出跟路径有关。

第二，确认目标盘符有足够空间。完整方案装完之后占用在 5GB 到 7GB 之间，再加上临时文件和后续用 tlmgr 补装的宏包，建议预留 15GB 以上。我见过有人把 TeXLive 装在只剩 3GB 的分区上，装到一半磁盘写满，安装器直接退出，留下的半成品环境比不装还麻烦。

第三，以管理员身份运行安装器。TeXLive 会往系统目录写字体配置文件、注册文件关联，权限不足时这些步骤会静默失败，你在装完之后才会发现问题。

第四，临时关闭安全软件的实时防护。这一点后面还会详细说，安装器会生成并执行大量临时脚本和小工具，安全软件的启发式规则很容易把它们当成可疑行为拦下来，表现出来就是"某个文件解压到一半不见了"。

第五，把正在运行的编辑器、文档阅读器全部关掉。TeXLive 安装过程会尝试更新系统的字体缓存，如果有程序正占用字体文件，这一步会失败但不报错。

注意：如果你已经在别处装过 MiKTeX，装 TeXLive 之前先把 MiKTeX 从 PATH 里摘掉，两个发行版同时挂在环境变量里，后面编译时用的是哪个你都说不准。

2. 安装包下载与镜像源：慢和断的根源

很多人吐槽 TeXLive 装得慢，其实慢的不是安装本身，而是包下载环节。TeXLive 的官方源在境外，直连速度经常在几十 KB 徘徊，一个完整方案拉下来能熬掉一下午。换镜像源是唯一有效的解法，但换源也有讲究。

2.1 镜像站怎么挑，下载器怎么配

国内主要的高校和云厂商镜像站都提供了 CTAN 的完整同步，比较常用的有清华 TUNA、中科大 USTC、以及几家云服务商提供的开源镜像。它们同步频率不同，一般延迟在几小时到一天之间，对普通使用来说完全无感。

选源的时候有个小技巧：不要只看"哪家名气大"，而是实际测一下速度。可以在浏览器里直接打开该镜像站的systems/texlive/tlnet/目录，看看里面的texlive.tlpdb文件能不能秒开，能秒开说明响应快。另外云厂商的镜像站在晚高峰时段往往比高校源更稳，因为高校源的带宽要同时服务校内用户。

如果在命令行安装，直接把源地址跟在-repository参数后面就行：

install-tl-windows.bat -no-gui -repository https://mirrors.ustc.edu.cn/CTAN/systems/texlive/tlnet

如果你选的是 ISO 路线，那么下载的就是一个完整的镜像文件。这时候建议用支持多线程和断点续传的下载工具，而不是浏览器自带的下载器。4GB 的文件用浏览器下到 90% 断掉，那种心情我体验过一次就够了。

下载完之后一定要校验。镜像站通常会同时提供校验值文件，用系统自带的证书工具或者命令行算一下哈希：

certutil -hashfile texlive2020.iso SHA512

比对一下结果。校验这一步别跳过，我遇到过因为下载不完整导致安装到一半报"读取失败"的情况，排查了两个小时才发现是文件本身缺了几十兆。

2.2 挂载还是解压，这一步有讲究

拿到 ISO 之后，很多人的第一反应是用解压软件把它解成一堆文件。这个做法能用，但有两个隐患。

第一是解压路径。如果你解压到桌面或者用户目录，路径里很可能带中文或者带空格，这又回到了前面说的路径问题。正确做法是解压到类似D:\texlive2020\这种纯英文、无空格的短路径下。

第二是权限位丢失。ISO 里有些文件带有特殊的属性标记，某些解压软件处理不当会导致文件权限异常，安装器读取时会报错。相对稳妥的方式是用 Windows 自带的挂载功能——右键 ISO 文件选"装载"，系统会把它挂成一个虚拟光驱，然后直接运行里面的install-tl-windows.bat。这样读的是原始文件系统，不会有解压引入的问题。

如果挂载之后运行报错说找不到源，可以检查一下光驱盘符有没有被占用冲突。少数机器上光驱盘符和网络驱动器盘符打架，虚拟光驱装载后分配到的盘符是乱的，手动改一下就好。

3. 安装过程中的典型报错逐个拆解

前面两步都顺利的话，安装过程本身一般二十分钟到四十分钟就能结束。但如果你卡在这里，下面三种情况基本覆盖了九成以上的失败场景。

3.1 "error while reading from perl backend" 到底是什么坏了

这个报错可以说是 TeXLive 安装里最有名的一条，我在论坛和群里见过无数次。它的字面意思是"从 Perl 后端读取数据时出错"，听起来像是安装器内部逻辑坏了，实际上它只是一个非常笼统的通信失败提示——安装器的图形前端和后台的 Perl 进程之间通过管道通信，任何导致这个管道断掉的原因都会报这句话。

我实际排查下来，触发它的原因主要有四类，按出现频率排序：

第一类是杀软拦截。安装器会临时生成perl.exe、tar.exe这些小工具并调用它们，安全软件的主动防御看到"一个程序释放另一个程序并立即执行"，很容易直接阻断。表现出来就是安装器跑到某个百分比突然报这个错，日志里能看到某个子进程异常退出。

第二类是路径问题。前面反复强调的中文用户名、带空格的安装目录，都会让 Perl 在拼接文件路径时出错。Perl 在 Windows 上对 Unicode 路径的支持一直不算好，这是个历史遗留问题。

第三类是安装介质不完整。ISO 下载缺字节、解压过程中断过，都会导致某个必须的包读不出来。

第四类是磁盘或内存异常。这个比较少见，但确实遇到过——一台机器的内存有故障，安装器跑到大量文件复制阶段时进程崩溃。

对应的处理办法，我按顺序建议这么做：

:: 1. 换个纯英文目录重新解压，比如 D:\tl2020\ :: 2. 用命令行模式绕过图形界面 install-tl-windows.bat -no-gui :: 3. 临时关闭安全软件实时防护后重试 :: 4. 重新校验 ISO 完整性 certutil -hashfile texlive2020.iso SHA512

命令行模式之所以管用，是因为它去掉了前后端通信这一层，报错信息会直接打印在控制台上，比图形界面里那句笼统的提示有用得多。你甚至能看到它具体是在处理哪个包的时候挂掉的，对定位问题帮助很大。

提示：安装器会在临时目录下留下日志文件，路径通常在%TEMP%下面，文件名带install-tl前缀。报错之后别急着删，打开日志翻到最后几十行，往往能直接看到真实原因。

3.2 中文用户名和中文路径引发的连锁反应

这个问题单独拎出来讲，因为它的表现特别有迷惑性。你可能会遇到安装顺利结束，但一编译就报错；或者 tlmgr 能运行但装不了新宏包；或者字体怎么都找不到。这些看似不相关的症状，根子都在同一个地方：某个配置文件被写到了一个含中文的路径下。

TeXLive 有一套自己的目录变量体系，其中TEXMFHOME、TEXMFCONFIG、TEXMFVAR这几个默认指向用户目录。如果你的用户名是中文，这些路径就带上了中文，Perl 脚本和部分宏包在读写这些位置时会失败。

最彻底的解决办法是新建一个纯英文名的本地账户，把 TeXLive 装在那个账户下。但对很多人来说换账户成本太高，那就用环境变量覆盖的方式绕过：

setx TEXMFHOME "D:\texmf\home" setx TEXMFCONFIG "D:\texmf\config" setx TEXMFVAR "D:\texmf\var" setx TEXMFLOCAL "D:\texmf\local"

设置完之后要重新打开命令行窗口才生效。这里有个细节：TEXMFLOCAL通常指向安装目录下的texmf-local，不用单独改也行，但把它和用户目录分开管理，后续清理和迁移会方便很多。

还有一个容易漏掉的点——安装器的 profile 文件。如果你是用-profile参数做批量化安装，profile 里会记录一堆目录路径。这个文件本身可以用记事本编辑，把里面所有路径改成纯英文的即可。这也是批量部署时最省事的做法：先在图形界面里配置一遍，导出 profile，改好路径，之后每台机器都用同一个 profile 装。

3.3 权限、安全软件和临时目录的组合拳

这几样东西单独拿出来都不算大问题，但它们凑在一起的时候，排查难度会直线上升。我遇到过一次特别典型的：安装器跑到 60% 左右无声退出，日志里只有一句"操作被中止"，没有任何错误码。最后查出来是安全软件拦截了安装器创建的临时脚本，同时系统的临时目录又恰好在用户目录下、路径含中文——两个问题叠加，报错信息被吞掉了。

处理这一类问题的思路是"逐个变量隔离"：

• 先把临时目录改到纯英文的短路径下，在命令行里临时设置set TEMP=D:\tmp和set TMP=D:\tmp，然后从同一个命令行窗口启动安装器。注意是临时设置而不是setx，这样只影响当前这个进程，不会污染整个系统。
• 再临时关闭安全软件的实时防护，装完再开回来。如果公司电脑有强制策略关不掉，可以联系管理员加白名单。
• 以管理员身份运行。右键安装器，选"以管理员身份运行"，不要图省事直接双击。

顺便说一句，安装器对网络中断的处理也不够优雅。如果你走的是在线安装，中途网络抖动了一下，它可能不会提示重试，而是默默跳过某个包继续往下走，最后装出来一个看似完整、实际缺东西的环境。判断方法很简单：装完之后跑一次完整性自检。

tlmgr verify-repo tlmgr check

tlmgr check会扫描已安装的宏包是否有文件缺失或损坏，输出一堆ok就说明没问题。

4. 装完别急着写文档，先做环境校验

安装器显示"完成"并不代表环境可用了。我在这一步吃过亏——装完之后直接用编辑器编译，报了一堆找不到命令的错误，回头查发现是环境变量没配好。先花五分钟做校验，能省掉后面半小时的困惑。

4.1 命令行验证与环境变量配置

打开一个全新的命令行窗口（一定要新开，环境变量的变更对已经打开的窗口不生效），依次运行：

tex --version latex --version xelatex --version pdflatex --version tlmgr --version

正常的话每一条都会输出版本号，并且显示是 TeX Live 2020。如果提示"不是内部或外部命令"，说明 PATH 没配好。

TeXLive 的二进制目录在安装目录下的bin\win32。注意别被win32这个名字骗了，在 64 位 Windows 上装的 TeXLive2020 用的也是这个目录名，这是官方一直沿用的命名。假设你装在D:\texlive\2020，那要加到 PATH 里的就是：

D:\texlive\2020\bin\win32

配置方式有两种。图形界面方式是在"系统属性 → 高级 → 环境变量"里找到 Path，新建一条。命令行方式是用setx：

setx PATH "%PATH%;D:\texlive\2020\bin\win32"

这里有个坑要提醒：setx写入的 PATH 长度有上限，如果你的 PATH 本来就接近极限，用setx可能会把后面的内容截掉，反而破坏其他软件的配置。这种情况下老老实实用图形界面改，或者直接编辑注册表里的HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment下的 Path 值。

注意：改完 PATH 后一定要关闭所有已打开的命令行和编辑器再重新打开。有些编辑器启动时会缓存环境变量，不重启的话它仍然找不到 tex 命令。

4.2 编辑器配置：TeXstudio 与 VS Code

命令行通了之后，接下来是编辑器。TeXLive 自带的 TeXworks 能用，但功能比较基础。国内用得多的是 TeXstudio 和 VS Code 两个选择，配置思路不太一样。

TeXstudio 的配置集中在"选项 → 设置 TeXstudio → 构建"里。关键是三处：默认编译器选 XeLaTeX（写中文文档更省心）、默认文献工具按需选 BibTeX 或 Biber、命令行参数加上-synctex=1 -interaction=nonstopmode。-synctex=1是为了支持正向反向搜索，写长文档时点一下 PDF 就能跳回源码，效率提升很明显；-interaction=nonstopmode是让编译遇到错误时不弹交互提示，直接继续跑完，方便在编辑器里统一看错误列表。

VS Code 走的是 LaTeX Workshop 插件路线，配置写在settings.json里。核心是定义编译工具链和配方：

{ "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", "tools": ["xelatex"] }, { "name": "xelatex -> bibtex -> xelatex x2", "tools": ["xelatex", "bibtex", "xelatex", "xelatex"] } ] }

-file-line-error这个参数值得单独说一句，它会让报错信息带上文件名和行号，输出格式是文件名:行号: 错误信息，VS Code 能直接识别这种格式并做成可点击的跳转链接。不加这个参数的话，错误信息只有孤零零的行号，得自己手动找。

配置完之后写个最小测试文档验证一下：

\documentclass[UTF8]{ctexart} \usepackage{amsmath} \begin{document} 中文排版测试。 行内公式 $E = mc^2$，行间公式： \begin{equation} \int_0^1 x^2 \, dx = \frac{1}{3} \end{equation} \end{document}

用 XeLaTeX 编译，能正常出 PDF 且中文不乱码、公式正常显示，说明整套环境通了。

5. 编译阶段的报错与宏包管理

安装本身搞定之后，日常使用中碰到的报错基本集中在两类：宏包缺失和字体问题。这两类问题的处理方式差别很大，分开说。

5.1 宏包缺失：tlmgr 的正确用法

最常见的报错长这样：

! LaTeX Error: File `xxx.sty' not found.

这说明你用的宏包当前环境里没有。处理方法是用 tlmgr 装：

tlmgr install xxx

但 tlmgr 本身有两个坑。第一个是仓库设置。TeXLive 的版本策略是每年发布一个新版，旧版的在线仓库会在次年新版发布后停止更新。TeXLive2020 现在已经不是当前版本了，默认仓库地址可能已经失效，tlmgr update会报连不上。这时候需要手动指向归档源：

tlmgr option repository https://texlive.info/tlnet-archive/2020/tlnet/

换完之后再执行tlmgr update --self --all就能正常更新了。如果你只是想在现有环境里补几个宏包，其实不用换源，直接从镜像站装就行：

tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet tlmgr install ctex tlmgr install algorithm2e

第二个坑是权限。如果你在安装时用了管理员权限，那么 tlmgr 装包时也要用管理员权限，否则它会试图往受保护目录写文件然后失败，报错信息通常是"没有权限写入某路径"。解决办法是以管理员身份打开命令行再执行 tlmgr。

还有一种情况值得一提：宏包名和实际文件名不是一回事。报错说的是缺少xxx.sty，但你要装的包名可能是yyy。这时候去 CTAN 网站搜一下那个.sty文件名，页面会告诉你是哪个包提供的。我见过有人对着一个.sty文件名在 tlmgr 里搜了半天搜不到，就是因为这个。

5.2 字体与中文排版报错

中文文档在 Windows 上的字体问题比 Linux 少一些，但也有一类高频报错：

! Package fontspec Error: The font "XXX" cannot be found.

原因通常是字体名写错了，或者系统里根本没装那个字体。Windows 下的中文字体内部名称和文件显示名经常对不上，比如"微软雅黑"的内部名是Microsoft YaHei，"宋体"是SimSun。用 fontspec 指定时要用内部名：

\usepackage{fontspec} \setCJKmainfont{SimSun} \setCJKsansfont{Microsoft YaHei} \setCJKmonofont{FangSong}

如果不想折腾字体名，直接用ctex宏包最省事，它会自动适配当前系统的可用中文字体：

\documentclass[UTF8]{ctexart}

还有一类报错跟编译引擎有关。用pdflatex编译含中文的文档经常报字体相关的错，因为 pdflatex 本身不支持 Unicode，得靠CJK宏包挂字体，配置繁琐。解决办法是换引擎，xelatex或lualatex都原生支持 Unicode，配合 fontspec 或 ctex 基本不会有字体问题。我的习惯是：写英文论文用 pdflatex（生态最成熟），写中文文档一律 xelatex。

5.3 常见报错速查表

下面这张表是我这几年零零散散记下来的，放在手边查比较方便。

提示：报错时养成先看日志文件末尾的习惯。日志一般在源文件同目录下，扩展名是.log，最后二十行往往就是真正的原因，比编辑器里显示的摘要信息精确得多。

6. 装完之后的一些长期维护心得

环境装好只是开始，TeXLive 用久了会有一些维护上的琐事，提前知道能少走弯路。

6.1 版本升级与多版本共存

TeXLive 不支持跨年度的原地升级，2020 升到 2021 只能重新装一遍。这看起来麻烦，但其实有个好处：你可以让多个版本并存。比如把 2020 装在D:\texlive\2020，2022 装在D:\texlive\2022，需要哪个版本就把哪个版本的bin\win32放到 PATH 前面。这个做法在需要复现老项目编译结果时特别有用——有些宏包在新版本里改了行为，用新版编译老论文会出现排版偏移，这时候切回旧版本就能解决。

如果确定不再需要 2020，卸载的方法是运行安装目录下的tlmgr uninstall，或者直接删目录加上清理环境变量。不要只删目录不清 PATH，留着一条指向不存在路径的记录会让命令行启动变慢，偶尔还会引发奇怪的报错。

6.2 备份与迁移的思路

TeXLive 的整个安装目录是可以直接打包带走的。这意味着你在一台机器上配好的环境，压缩后拷到另一台机器上，改一下 PATH 就能用，不用重新装一遍。我在换电脑的时候就是这么干的，省了大半天时间。

具体做法是先清理掉缓存和临时文件，安装目录下有个tlpkg\temp之类的临时目录可以删，然后整个2020目录压缩。因为是绿化性质，目标机器的用户名和路径不同也没关系，只要改 PATH 指向新的位置就行。

不过有一点要注意：用这种方式迁移之后，tlmgr 的配置里可能还记着原来的路径。跑一次tlmgr option repository <新地址>覆盖一下，或者直接删掉用户目录下的.texlive相关配置文件让它重新生成。

我自己这几年的体会是，TeXLive 这套东西的安装和配置难度，八成集中在 Windows 环境适配这一块，跟 TeX 本身反倒没什么关系。路径别带中文、权限给足、杀软让路、源换到国内，这四件事做到位，剩下的基本就是一路回车。真正容易反复踩的是那些报错信息特别笼统的场景，比如那个 perl backend 报错，字面意思和实际原因差得远，所以遇到看不懂的错误时，与其盯着那句话猜，不如直接从"权限、路径、防护软件、文件完整性"这四个维度挨个排除，效率高得多。