每次帮别人装环境TeXLive2020 的安装环节基本都是耗时最长、也最容易出岔子的一步。我自己前前后后在 Windows、Linux 还有 macOS 上都折腾过几轮踩过的坑从下载一整天还没结束到装完找不到命令再到中文一编译就报字体缺失基本上能遇到的都遇到了。这篇就把这些真实的翻车经历和对应的解决思路整理出来讲清楚每个问题背后的原因也给出可以直接照着做的步骤。如果你正准备装 TeXLive2020或者说装到一半卡住了、装完之后环境不对这篇内容都能帮上忙。它不是什么官方文档的翻译而是我自己在一台台机器上试出来的经验适合刚接触 LaTeX 的新手也适合同样在帮别人配环境的老手参考。下面按照准备、下载、安装、配置、使用的真实顺序往下讲每一步都会说清楚为什么这么做。1. 动手之前先把这三件事确认清楚很多人装 TeXLive2020 失败问题其实不在安装本身而是开始之前没做检查。我见过太多次装到 80% 报错、或者装完了发现路径不对只能重来的情况。花五分钟把下面几件事确认好能省下好几个小时。1.1 磁盘空间和安装路径的硬约束TeXLive2020 的完整版安装full scheme占用空间在 5GB 到 7GB 之间具体取决于你选的安装方案。它的 ISO 镜像文件本身大约 3.7GB解压安装之后还要占用更多。所以第一件事就是确认目标盘符至少留出 10GB 的空闲空间别等到解压到一半提示磁盘不足那种失败清理起来特别麻烦。安装路径这条我要重点说。路径里绝对不能有中文和空格这是 TeXLive 系列一贯的脾气。很多人习惯装在C:\Program Files\texlive\2020那个空格会让后面一些脚本解析路径时出问题更麻烦的是装在D:\我的软件\TeXLive这种带中文的目录下某些工具链直接就没法识别。我的建议是老老实实装在默认的C:\texlive\2020或者 Linux 下的/usr/local/texlive/2020。看着朴素但省心。提示如果你想把发行版装到非系统盘可以在安装器里改目录但一定要保证目录名是纯英文、无空格、层级不要太深。我一般用D:\texlive\2020这种形式。1.2 关掉实时防护这一步真的不能省Windows 上装 TeXLive 有个特别隐蔽的坑杀毒软件的实时防护会在解压成千上万个文件的时候逐个扫描导致安装速度慢到离谱甚至误报某些可执行文件为威胁直接删掉。我自己就遇到过装完之后xelatex.exe莫名其妙不见了的情况查了半天才发现是被实时防护拦截了。所以在开始安装之前临时关闭杀毒软件的实时监控或者至少把安装目录加入白名单。装完之后再恢复正常防护。这一步花不了几秒但能避免很多诡异的文件消失问题。Linux 下基本没这个问题但如果你用了某些强制访问控制策略也要注意安装目录的权限。1.3 想清楚自己需要哪个安装方案TeXLive 提供了几种安装方案full全量、medium、basic、scheme-small 等等。很多人一上来就选 full觉得全装最省事。这想法没错full 方案确实省去了后面补装宏包的麻烦但它对磁盘和网络的要求也最高。如果你的硬盘紧张、网络又不稳定选 basic 之后再按需装宏包反而是更稳的策略。我的判断标准很简单常年写论文、做演示、需要各种宏包的人直接上 full只是偶尔写个简单文档、或者磁盘空间有限的选 basic 加tlmgr按需补装。这个决定要在下载之前做因为不同方案的安装器体积和安装时长差得很远。2. 下载与镜像源为什么你的安装器慢得让人怀疑人生下载环节是劝退率最高的一步。官方的下载服务器在海外国内直连的速度经常只有几十 KB 每秒一个 3.7GB 的镜像下一天都下不完。这一节讲清楚怎么选镜像、怎么判断下载器是不是真的在干活。2.1 ISO 完整镜像和在线安装器的取舍TeXLive 有两种主流的安装方式各有各的适用场景我在下面这张表里对照一下安装方式体积优点缺点适合谁ISO 完整镜像约 3.7GB一次下载永绝后患可离线安装网络中断不影响下载耗时长需要额外挂载步骤网络稳定但速度慢、或者要给多台机器装在线安装器 install-tl约 20MB下载快按需拉取所需文件安装过程持续联网中途断网会失败网络质量好、只装一台机器我个人的偏好是如果能找到一个速度还行的镜像站直接下 ISO 更安心。因为在线安装器在整个安装过程中都保持网络连接一旦某个宏包下载超时整个流程可能就中断了重试成本很高。ISO 下载虽然也是一次性的大文件但它断点续传友好下载工具能接着传。2.2 国内镜像站的选择逻辑国内有几个高校和机构维护的镜像站点速度和稳定性都不错。选镜像的时候不用纠结哪个最好原则就一条哪个离你网络近、速度快就用哪个。常见的思路是先试自己所在区域教育网的镜像往往比运营商线路的镜像更快。拿到镜像地址之后如果是用在线安装器可以在安装时指定仓库地址。例如用命令行安装的话大致是这样# 指定使用某个镜像作为安装源具体地址换成你选定的镜像 ./install-tl -repository https://mirror.example.edu/CTAN/systems/texlive/tlnet如果你已经装好了一部分想中途换源续传那就要看具体安装器是否支持了多数情况下直接重来会更省事。这也是我更推荐 ISO 的原因之一。注意镜像站的目录结构通常和 CTAN 保持一致路径里要包含systems/texlive/tlnet这一段少写或者写错都会导致找不到文件。复制地址的时候一定要完整。2.3 怎么判断下载是不是真的卡住了下载速度慢和下载彻底卡死是两回事得学会区分。浏览器或者下载工具上显示的速度如果还在跳动哪怕只有几十 KB那说明它还在传只是慢。真正卡死是速度长时间为零、进度条一动不动。这时候先别急着取消等个三五分钟看看有时候是服务器在响应大文件的分段请求。如果确认卡死了优先换镜像重试而不是反复重连同一个源。我遇到过某个镜像在某段时间对某个大文件就是响应很慢的情况换成另一个镜像立刻就正常了。另外提醒一句有些下载工具默认线程数开得很高反而会被服务器限速把并发数降到 4 到 8 之间往往更稳。3. 安装中途卡死、报错与中断的完整排查链路终于开始安装了这才是真正的战场。TeXLive2020 的安装过程涉及解压几万个文件、写入注册表Windows、配置环境出问题的概率不低。我把常见的问题按现象分类一步步给出排查方法。3.1 正在解压某个文件长时间不动到底是不是卡了安装到一半屏幕上停在某一行正在解压 xxx不动了这种情况特别常见。先别慌TeXLive 在解压某些体积较大的宏包时确实会停顿一段时间尤其是那种包含大量字体文件或者文档的包。判断方法很简单打开任务管理器Windows或用topLinux看安装进程的 CPU 或者磁盘 IO 有没有活动。如果磁盘还在读写那就是在正常干活耐心等。如果确认进程完全没动静、磁盘 IO 也归零了那大概率是真卡了。这时候的罪魁祸首通常是杀毒软件实时扫描回到 1.2 节或者磁盘出现坏道。前者关掉实时防护重装即可后者就得考虑换盘了。3.2 权限不足导致的写入失败Windows 上如果安装目录在系统盘而你没有用管理员权限运行安装器写到一半就可能报权限错误。Linux 下如果装在/usr/local而没加sudo同样会失败。这类报错的特征是错误信息里带拒绝访问permission denied之类的字眼。解决办法很直接Windows 上右键安装器选择以管理员身份运行Linux 上用sudo执行sudo ./install-tl但要注意用sudo装完之后整个 texlive 目录的所有者是 root后面普通用户操作可能会有权限问题。Linux 下更稳妥的做法是装在自己家目录例如/home/你的用户名/texlive/2020这样全程不需要 root 权限也不会污染系统目录。3.3 中断之后重装前的清理工作安装中断之后很多人直接重新运行安装器结果报目录已存在或者各种莫名其妙的冲突。这是因为上一次安装已经写入了部分文件和配置。中断后重装前一定要把目标安装目录彻底删干净不能只删一部分。Windows 下还要额外清理这几处安装目录本身比如C:\texlive用户目录下的.texlive2020文件夹在C:\Users\你的用户名\下如果之前手动配过环境变量把 PATH 里相关的条目也删掉Linux 下则是~/texlive、~/.texlive2020这些位置。清干净之后再重装能避免绝大部分重装依然失败的情况。我踩过这个坑当时反复重装三次都失败最后发现是旧配置没清。4. 装完却找不到命令PATH 与环境变量的排查过程安装显示成功了打开终端敲tex --version却提示不是内部或外部命令或者command not found。这个问题的本质就一句话可执行文件所在的目录没有加到 PATH 里。但具体排查起来不同系统有不同讲究。4.1 先验证安装是不是真的完整在配 PATH 之前得先确认安装本身没出问题。直接去安装目录里找可执行文件WindowsC:\texlive\2020\bin\win32\下面应该有tex.exe、latex.exe、xelatex.exe等等Linux/usr/local/texlive/2020/bin/x86_64-linux/下面有对应的可执行文件如果这些文件都在说明装好了问题就是 PATH如果目录里空空如也或者缺文件那就是安装本身失败了得回上一节重新排查。先定位问题在哪一层再动手解决别一上来就改环境变量那样可能白忙活。4.2 Windows 与 Linux 下 PATH 配置的差异Windows 下配置 PATH 的步骤右键此电脑选择属性进入高级系统设置点环境变量在系统变量里找到Path编辑新增一行安装目录的 bin 路径保存之后必须重新打开命令行窗口旧窗口不会自动加载新配置Linux 下则是编辑 shell 的配置文件比如~/.bashrc或者~/.zshrc加一行# 把 texlive 的 bin 目录加入 PATH export PATH/usr/local/texlive/2020/bin/x86_64-linux:$PATH加完之后执行source ~/.bashrc让它立即生效。这里有个细节要把 texlive 的路径放在 PATH 前面否则如果系统里之前装过其他版本的 TeX 发行版可能会优先调用旧的。4.3 多版本共存的冲突处理有些人的机器上可能同时有 TeXLive2020 和一个更早的版本或者系统自带的tex-common之类的东西。这时候就出现了命令能找到但版本不对的情况。判断方法很直接which tex # 看看输出的路径到底指向哪个版本的 bin 目录如果指向的不是你新装的 2020 版本就说明 PATH 的顺序有问题或者旧版本在更靠前的位置。解决办法要么调整 PATH 顺序要么把旧版本从里面移除。我一般会干脆把旧版本卸载掉避免以后反复被坑。5. tlmgr 宏包管理装完之后真正天天要用的东西装完 TeXLive 只是开始真正天天打交道的是tlmgr这个宏包管理器。缺宏包了要装、想更新要跑更新这里面也有不少门道尤其是跨版本更新那块踩过的坑特别多。5.1 换用国内镜像仓库加速宏包更新刚装好的 TeXLive 默认仓库地址指向官方源tlmgr更新宏包的时候同样慢。第一件事就是把仓库换成国内镜像# 查看当前仓库地址 tlmgr option repository # 修改为国内镜像 tlmgr option repository https://mirror.example.edu/CTAN/systems/texlive/tlnet换成国内镜像之后更新和安装宏包的速度会有明显提升。建议一开始就设好别等到被慢速度折磨了才想起来换。5.2 缺宏包时的两种解决路径编译文档时报Filexxx.sty not found就是缺宏包了。解决路径有两条一是用tlmgr 装二是手动下载放到本地目录。我强烈推荐前者# 安装指定的宏包 tlmgr install 宏包名用tlmgr装的好处是它会同时处理依赖省去你自己找依赖包的麻烦。手动下载.sty文件放到文档目录虽然能应急但长期看容易造成依赖缺失、版本混乱不太推荐日常使用。提示遇到宏包名不确定的时候可以去 CTAN 上搜一下对应的功能关键词通常能找到确切的包名。找到名字再用tlmgr install装。5.3 跨版本更新为什么会失败这是个经典问题想用tlmgr update --self --all把 2020 更新到最新状态结果报一堆错。原因是TeXLive 的仓库只保留当前版本和上一个版本的宏包一旦官方发布了 2021 或者其他新版本2020 的仓库地址就会失效或者被替换导致更新失败。面对这种情况有两条路一是继续用 2020 不动只要它能编译你的文档就够二是升级到新版本。TeXLive 不支持原地跨版本升级只能用新版本的安装器重新装一遍然后卸载旧版本。所以如果你有更新强迫症会有动力。但说实话只要现有版本能满足编译需求硬着头皮升级的收益并不大。现象可能原因处理办法tlmgr update报仓库失效官方已下线旧版本仓库冻结当前版本按需手动装宏包更新后部分宏包报错宏包版本与主程序不匹配回退或重装对应宏包安装宏包一直卡住仓库地址慢或网络问题换成国内镜像后重试6. 中文排版与字体从能编译到排得对对中文用户来说最头疼的往往不是装 TeXLive 本身而是装完之后中文没法正常编译。这一节专门讲中文字体和编译链路的问题。6.1 字体缺失报错的定位方法用一个带中文的文档测试编译如果报Font xxx not found或者字形乱码基本就是字体配置的问题。TeXLive 自带了一部分字体但中文字体通常需要你自己配置或者依赖系统的字体。现在的推荐做法是用ctex宏包配合xeCJK它对中文字体的处理比较成熟。一个最小的测试文档长这样\documentclass[UTF8]{ctexart} \begin{document} 你好这是一段中文测试。 \end{document}用xelatex编译这个文档如果能正常出 PDF说明中文字体基本没大问题。如果报错就要检查ctex宏包有没有装全以及系统里有没有对应字体。Linux 上字体缺失比较常见可以用fc-list :langzh看看系统里有哪些中文字体。6.2 编译链路的参数差异有个很多人不知道的点编译中文必须用xelatex或者lualatex不能用老的pdflatex。pdflatex对中文和 Unicode 的支持很有限用它编译中文文档大概率出问题。所以配置编辑器的时候一定要注意把默认的编译工具链改成xelatex。VS Code、TeXStudio 这些编辑器默认可能是pdflatex不改的话中文一编译就报错很多人会误以为是宏包的问题其实是编译命令用错了。这个点值得单独记一下。7. 编辑器的配合配置细节决定使用体验TeXLive 只是引擎日常写文档还得配个顺手的编辑器。这一节讲 VS Code 和 TeXStudio 这两款常用编辑器在配合 TeXLive2020 时的配置要点。7.1 VS Code 下的 LaTeX 配置VS Code 配 LaTeX 主要靠 LaTeX Workshop 插件。装好插件之后要在设置里指定编译工具链。默认配置对中文用户不太友好需要手动改成xelatex。插件的配置文件里tools和recipes这两部分决定了用什么命令、按什么顺序编译。中文文档建议配置一条xelatex的 recipe。还有一个容易被忽略的点latexmk的自动编译。它能在你每次保存文件的时候自动重新编译配合 PDF 预览非常舒服。但如果配置不当可能会导致编译进程反复重启占满 CPU。遇到这种情况检查一下recipes里是不是有循环依赖或者关掉保存自动编译、改用手动触发。7.2 TeXStudio 的默认设置调整TeXStudio 对新手更友好界面直观但它的默认编译命令同样是pdflatex。第一次打开中文文档编译报错的时候很多人会懵。解决方法是去选项里的构建设置把默认编译器改成xelatex。改完之后中文就能正常编译了。另外 TeXStudio 有个自动检测的选项有时候会卡在检测状态。我一般会关掉自动检测手动指定用xelatex这样更可控。7.3 编译过程中常见的编辑器相关报错有时候不是 TeXLive 的问题而是编辑器和语言服务器之间的通信出了岔子。比如 LaTeX Workshop 的语法检查偶尔会把正常的命令标红这只是检查器的误报不影响实际编译。遇到编辑器报错但命令行编译正常的情况先去命令行验证一遍能编译就不用理会编辑器的提示。真正的编译错误会在日志文件里通常看xxx.log里第一条!开头的错误信息最有用。别被编辑器里铺天盖地的红色吓到绝大多数都是次要信息找准第一个真正的错误才是关键。我在几个系统上反复装 TeXLive2020 之后最大的体会是安装的坑基本都集中在网络、路径、权限这三件事上装完之后的使用坑则集中在PATH、字体、编译命令上。把这几处捋清楚了剩下的就是熟练度问题。最后分享个小习惯我每次装完都会用一个带中文的最小文档编译一遍做验证能出 PDF 才算真装好不然光看安装器显示成功是不靠谱的。