TeXLive2020安装这件事说难不难说简单也确实能把人卡上大半天。我在三台配置完全不同的机器上装过这套环境——一台是老笔记本上的机械硬盘、一台是刚配的开发机、还有一台是同事装了半截放弃甩给我的办公电脑三次遇到的报错几乎不重样。TeXLive 本身是一套相当完整的发行版装完之后宏包齐全、开箱能用这也是很多人宁愿忍受几个G的下载量也要选它的原因但它毕竟是一套从 Unix 世界移植过来的工具链安装器用 Perl 写的对 Windows 环境里那些中国特色路径、杀软拦截、权限限制的容忍度并不高。这篇内容我打算把安装前该排的雷、安装包下载和镜像选择、安装器跑到一半崩掉的几种典型报错、装完之后的校验和编辑器配置、以及后面写文档时的宏包与字体问题全部按我实际处理过的顺序讲一遍。适合第一次接触 TeXLive 的新手也适合装到一半报错卡住、想找具体原因的老用户。我尽量不写那种照着官网文档念一遍的东西重点放在报错背后的原因和可以直接抄的操作上。1. 安装前不排雷后面全是坑TeXLive 的安装器有个特点它在正式开始复制文件之前会先跑一段 Perl 脚本做环境探测和方案计算这一步出问题的概率比你想象的高得多。而一旦这一步挂了报错信息往往非常模糊你根本不知道是路径的问题、权限的问题还是网络的问题。所以与其装到一半再回头折腾不如先把环境理干净。1.1 三种安装路线先想清楚自己要走哪条TeXLive2020 在 Windows 上有三种比较主流的安装路径它们对应的时间成本、容错能力和适用场景差别很大很多人卡住其实是因为一开始就选错了路线。安装方式下载体积耗时百兆宽带容错性适合谁网络在线安装install-tl-windows.bat 直连镜像源按需拉取完整方案约 5GB 以上40 分钟到数小时取决于源速度差中途断网就重来网络稳定、想要最新宏包的人ISO 镜像离线安装约 4GB 出头的 iso 文件下载 20 到 60 分钟安装 20 到 40 分钟好断网也能装完网络不稳、要装多台机器基础方案 tlmgr 按需补包首次约几百 MB20 分钟左右最好各步独立硬盘紧张、只用固定几个宏包的人我个人的建议是如果你不是非得追最新宏包直接走 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 TEMPD:\tmp和set TMPD:\tmp然后从同一个命令行窗口启动安装器。注意是临时设置而不是setx这样只影响当前这个进程不会污染整个系统。再临时关闭安全软件的实时防护装完再开回来。如果公司电脑有强制策略关不掉可以联系管理员加白名单。以管理员身份运行。右键安装器选以管理员身份运行不要图省事直接双击。顺便说一句安装器对网络中断的处理也不够优雅。如果你走的是在线安装中途网络抖动了一下它可能不会提示重试而是默默跳过某个包继续往下走最后装出来一个看似完整、实际缺东西的环境。判断方法很简单装完之后跑一次完整性自检。tlmgr verify-repo tlmgr checktlmgr 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新建一条。命令行方式是用setxsetx 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、命令行参数加上-synctex1 -interactionnonstopmode。-synctex1是为了支持正向反向搜索写长文档时点一下 PDF 就能跳回源码效率提升很明显-interactionnonstopmode是让编译遇到错误时不弹交互提示直接继续跑完方便在编辑器里统一看错误列表。VS Code 走的是 LaTeX Workshop 插件路线配置写在settings.json里。核心是定义编译工具链和配方{ latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [-synctex1, -interactionnonstopmode, -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 常见报错速查表下面这张表是我这几年零零散散记下来的放在手边查比较方便。报错信息关键词大概率原因处理办法error while reading from perl backend杀软拦截、路径含中文、介质不完整关防护、换纯英文目录、校验 ISO、改用命令行安装File xxx.sty not found宏包未安装tlmgr install 包名Font XXX cannot be found字体名写错或未安装用内部字体名或改用 ctex命令行提示 tex 不是内部或外部命令PATH 未配置添加安装目录\bin\win32到 PATH 后重开窗口tlmgr update 连不上仓库旧版仓库已冻结指向归档源或改用镜像站编译卡住不动交互模式等待输入加-interactionnonstopmode中文显示为方框或乱码引擎不支持 Unicode换 xelatex 或 lualatex磁盘写满导致安装中断空间不足清理后重装预留 15GB提示报错时养成先看日志文件末尾的习惯。日志一般在源文件同目录下扩展名是.log最后二十行往往就是真正的原因比编辑器里显示的摘要信息精确得多。6. 装完之后的一些长期维护心得环境装好只是开始TeXLive 用久了会有一些维护上的琐事提前知道能少走弯路。6.1 版本升级与多版本共存TeXLive 不支持跨年度的原地升级2020 升到 2021 只能重新装一遍。这看起来麻烦但其实有个好处你可以让多个版本并存。比如把 2020 装在D:\texlive\20202022 装在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 报错字面意思和实际原因差得远所以遇到看不懂的错误时与其盯着那句话猜不如直接从权限、路径、防护软件、文件完整性这四个维度挨个排除效率高得多。