TeX Live 的安装问题说到底是三个层面的问题叠在一起版本选错、下载源不对、装完之后环境没配对。上周我远程帮一个朋友排查安装失败从晚上九点折腾到十一点最后看到终端里出现Welcome to TeX Live那一刻我长出一口气。这篇文章就把这次已解决的完整过程拆开写顺便把我这些年踩过的 Texlive 安装相关的坑一并清点一遍。1. 装 Texlive 之前先把版本、镜像和磁盘这三件事定下来1.1 版本选择网络安装版、DVD 版还是 TinyTeX很多人在装 TeX Live 的第一步就走错了他们直接去官网首页找链接下载了一个不知道是网络安装器还是完整镜像的包。官网上的下载链接看起来都一样实际差得远。目前常用的安装来源有三种我标个对比安装方式体积适合场景主要坑点install-tl.zip网络安装版3MB 左右启动器安装时按需下载绝大多数人的最佳选择安装时网络不稳会导致各种奇怪报错install-tl.iso全量镜像单张 DVD 约 4-5GB无网络环境、离线安装下载慢挂载解压后容易遇到文件路径问题TinyTeX 引导版很小按需拉取宏包对磁盘空间敏感、只想用基础功能后续要自己手动补宏包不适合完整工作流我的建议很直接优先选网络安装版install-tl.zip。它不是一个完整的发行版而是一个引导程序你运行它之后它会根据你选的 scheme方案从仓库拉取对应宏包和工具。装完节省了大量本地空间而且以后想补包直接用tlmgr拉。官方提供的完整 ISO 文件虽然可以离线用但你要等一个 4GB 的下载装的时候全量展开还特别慢普通用户完全没必要。1.2 镜像源和校验最容易被忽略的两步很多人把install-tl.zip下载下来就迫不及待双击运行结果在安装进行到一半被各种问题卡住。这里有两个细节我每次重装都会执行第一不要直接使用官网默认仓库地址。官方提供的 CTAN 网络仓库在高峰期非常不稳定尤其你在校园网或者公司内网里连接很容易中断。我一般固定用清华 TUNA 镜像或者中科大 USTC 镜像选一个稳定的镜像能省掉一半麻烦。下面是两个常用源替换repository-path时直接用即可清华镜像https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/中科大镜像https://mirrors.ustc.edu.cn/CTAN/systems/texlive/tlnet/第二下载完install-tl.zip先校验压缩包完整性不要直接解压。压缩包如果在下到一半断了但浏览器仍显示成功解压时会出现缺失文件安装时必然报错。Windows 上可以用 PowerShell 跑校验Linux 用sha256sum。官网或者镜像站会提供对应的哈希值先对比再动它。另外安装前检查一下磁盘空间。全量安装scheme-full会占用 8GB 以上基础方案scheme-small也要 2GB 左右。我当时帮朋友排查时第一眼看到的就是他 C 盘剩余空间只有 800MB装到中途直接提示No space left on device我让他清理完临时文件再重来问题就没了。可以先执行df -hLinux/macOS或者看系统盘的剩余空间确认足够再开始。2. 实测踩坑一次完整安装的排查链路已解决2.1 坑一install-tl.zip解压正常终端却说脚本无效朋友那晚遇到的第一个报错就是他用 Windows 自带解压工具解压了install-tl.zip然后双击install-tl.bat弹出一个窗口三秒就消失什么都没发生。这个问题我遇到太多次根子通常不在 Texlive而在解压环节。Windows 自带的资源管理器解压对符号链接和脚本权限的支持很弱Texlive 安装包内部有一些 perl 脚本和符号链接解压不完整后脚本就无法执行。我让他换用 7-Zip 重新解压到D:\texlive-src这样的路径不要在路径里带中文和空格然后再从命令行进入该目录执行install-tl-2025\install-tl.bat如果你看到窗口还是一闪而过可以按住Shift 右键选择在终端中打开改成在 PowerShell 里运行.\install-tl-2025\install-tl.bat这样就算报错也能看到具体的错误信息而不是一闪而过的黑窗口。第二个隐藏问题是杀毒软件拦截。我朋友的 Windows Defender 实时保护会把install-tl.bat里调用 perl 创建大量小文件的行为当成可疑操作导致脚本在中途被静默终止。我让他把整个D:\texlive-src目录加入白名单再执行一次速度肉眼可见地快了很多。2.2 坑二安装进度停在某个 collection反复重试还是中断在我帮他换了解压方式、绕过杀毒拦截后安装终于跑起来了。但好景不长进度条走到了某个collection然后一直显示类似downloading ... timeout或者cannot resolve host卡在那里不动。这就是典型的网络仓库不稳定导致的问题。安装器使用的默认仓库是官方源而我们的网络环境访问它并不稳定。虽然安装器本身支持断点续传但如果仓库连接反复超时重试几十次也照样失败。解决办法是在启动安装器时显式指定稳定的镜像源perl install-tl --repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/在 Windows 上只需要打开 PowerShell进入解压目录后执行.\install-tl-2025\install-tl-windows.bat --repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/如果你不想敲命令也可以直接打开刚生成的texlive.profile配置文件把repository的值改成上面的镜像地址然后再执行安装。注意一点尽量保持网络的干净和稳定。如果你电脑上还跑着多个占用带宽的软件或者挂了很多学习资料下载任务安装器几十个线程同时拉包很容易中途超时。我一般会在安装期间把不相关的联网软件关掉只保留下载进程再配合镜像源基本一次过。2.3 坑三Linux 下提示缺少 perl 模块后来朋友换了一台 Ubuntu 机器重新安装报错又变了弹出来类似perl: command not found或者Cant locate Tk.pm in INC。这里说明一下TeX Live 的安装器本质上是一组 perl 脚本如果你的 Linux 发行版里 perl 不完整或者根本没装安装流程就没法启动。Linux 下大多发行版默认都有 perl 环境但有些精简版系统只装了最基础的 perl缺少额外的模块。比如 Debian/Ubuntu 官方源里的install-tl会依赖perl-tk用于图形界面安装如果你在无桌面环境下跑install-tl它会提示缺perl-tk但这其实不影响命令行安装你可以忽略图形界面直接选择命令行模式。我踩过更典型的坑是系统本身没有 perl我又用sudo执行安装脚本导致环境变量和用户环境不匹配报错定位起来特别困难。正确做法是先检查 perl 是否正常perl -v如果没有输出就先补装# Debian/Ubuntu sudo apt update sudo apt install perl perl-tk perl-doc装完 perl 再重新跑安装器。还有一个小技巧使用install-tl的-gui text参数强制走纯文本界面能避开因为缺少图形库引发的报错。perl install-tl -gui text --repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/2.4 坑四装完编译一个最小文档xelatex 找不到安装脚本终于走完终端显示安装成功但当我敲下xelatex --version时系统直接回复command not found。这个问题几乎是所有新手都会遇到的坎TeX Live 安装完成 ≠ 系统能直接用。原因是安装器默认不会自动把可执行文件目录加进系统 PATH。TeX Live 的二进制目录在 Linux 上通常是/usr/local/texlive/2025/bin/x86_64-linux在 Windows 上是C:\texlive\2025\bin\windows你需要手动把这个目录加到环境变量。Linux 下如果你用 bash可以在~/.bashrc里加export PATH/usr/local/texlive/2025/bin/x86_64-linux:$PATHWindows 下则通过系统属性 → 环境变量 → 用户变量 → PATH里新增上述路径。我当时帮朋友排查时发现他把路径写成了C:\texlive\2025\bin漏了windows子目录这导致一切都不生效。所以这里再多说一句先看一眼安装目录下到底有没有bin\windows或bin/x86_64-linux别猜路径。3. 收尾配置安装成功只算完成了六成3.1 tlmgr 的使用逻辑别一上来就update --all能在终端敲出xelatex --version看到大段版本信息之后只说明安装基本成功。还剩下最容易被忽略的一步使用包管理器tlmgr确认宏包的完整性。很多人装完就急着写论文等编译时提示缺少某个.sty文件比如经典的File comment.sty not found又回来折腾。正确的收尾动作是先更新包管理器自身tlmgr update --self然后按需安装你需要的宏包不建议直接全量更新。全量更新会把仓库里的所有宏包拉一遍费时费力而且有些宏包的新版本在几天内可能有兼容性问题反而让你刚配好的环境变得不稳定。我在每个新项目开始前会先确认latexmk、xelatex、bibtex这三个工具能够正常调用。这三个覆盖了大多数中文论文和报告的工作流需求。如果需要某个具体宏包再执行tlmgr install 宏包名比如缺少comment.sty就是tlmgr install comment3.2 中文支持CTeX 宏包和字体是两个独立问题TeX Live 安装完成后中文文档编译始终是高频问题。很多人更新宏包之后还是编译不了中文文档问题往往出在字体层。在 Windows 上系统自带中文字体一般可以直接跑\documentclass[UTF8]{ctexart} \begin{document} 你好世界。 \end{document}在 Linux 上就不一样了即使装了ctex宏包系统里没有可用的中文字体编译也会失败。所以我建议在 Linux 桌面环境下额外安装 Noto CJK 字体# Debian/Ubuntu sudo apt install fonts-noto-cjk # CentOS/RHEL sudo yum install google-noto-sans-cjk-fonts字体层搞定后善待用xelatex编译而不是pdflatex。ctex宏包配合xelatex是最省心的中文方案底层直接走系统字体接口不需要自己指定字体路径。3.3 工作流验证一份带参考文献的最小文档我习惯安装后的最后一件事是建一个临时目录编写一份包含中文、引用和图片的最小文档从零编译一遍确认整条工作流已经打通。下面这个例子我测过无数次可以直接拿去跑\documentclass[UTF8,a4paper]{ctexart} \usepackage{graphicx} \title{TeX Live 安装验证} \author{Me} \begin{document} \maketitle \section{概述} 这里是一段中文测试内容验证 xelatex 下 ctex 宏包工作正常。 \section{引用测试} 这句引用自文献 \cite{key2024}。 \begin{thebibliography}{9} \bibitem{key2024} 作者. 标题[M]. 出版社, 2024. \end{thebibliography} \end{document}编译命令顺序是有讲究的尤其是带参考文献的文档一次xelatex没办法把所有引用关系都解析出来。我通常跑四遍xelatex main.tex bibtex main xelatex main.tex xelatex main.tex很多人只知道一条xelatex main.tex结果参考文献区域变成问号就以为是宏包问题。再强调一次第一次xelatex生成.aux文件bibtex读取.aux并提供参考文献数据最后再做两次xelatex完整解析引用关系。跑完这套流程PDF 页码和参考文献都能正常显示。4. 其他零碎问题与最终建议4.1 安装器里的 scheme 选择全量还是精简在安装器里你会看到一个关键选项scheme安装方案。默认的全量方案是scheme-full也就是把所有宏包都装进去体积巨大且耗时但如果你用scheme-basic又能省到连常见文档类都没有。我给出的选择逻辑很简单你的使用场景推荐 scheme学生写论文、日常排版scheme-medium中等方案安装后按需补包专业 LaTeX 重度用户scheme-full全量方案一劳永逸只想写最简单的文档scheme-small之后按需用 tlmgr 补我自己现在固定用scheme-medium再配合tlmgr install补包。理由很简单全量装的 90% 宏包我这辈子都用不上而等论文 deadline 逼近时从tlmgr里单独拉一个几十 KB 的宏包比当初多花半小时装全量要划算得多。安装器还提供collection级别的细粒度选择比如文档类合集、图片工具合集、数学工具合集。如果你发现某个功能缺失直接用tlmgr collection install 收藏集名补装即可。4.2 系统环境牵扯的问题一是别误判二是分清排查范围扩展说一个容易让人困惑的情况。搜索引擎里Texlive 安装问题的相关联想词里有不少其他软件的安装词比如 OnlyOffice、Cherry 之类的安装报错甚至还有关于关闭主板超线程、开启 VT-x 这类系统级配置的讨论。这些内容乍看和 TeX Live 没关系但实际上它们反映了一个共性问题当系统里同时存在多个大型开发环境时安装任何软件都可能触发环境冲突。我遇到过一位做工业控制的同学他电脑里装了基于 Windows 实时内核的工控软件后来装 TeX Live 时老出现莫名的卡死一开始他以为是 TeX Live 安装包坏了。查到最后发现是主板 BIOS 里虚拟化相关的设置被改过导致实时内核与普通应用的内存调度产生冲突。这种问题和 TeX Live 本身没有任何关系但因为它发生在安装 Texlive 的过程中很容易让人误判成Texlive 没装好。我只提醒一句出现非常规的系统级异常时先分清问题归属别在 TeX Live 的安装参数上反复折腾。CPU 超线程、虚拟化这类系统级配置确实会影响某些工业软件和虚拟机环境但对 TeX Live 的编译和安装不产生决定性作用。排查优先级应该是网络仓库问题 → 解压问题 → 路径问题 → 系统环境冲突由简到难逐步推进。4.3 我这些年积累的三个早知道就好了的习惯我在反复安装 Texlive 若干次之后沉淀了三个特别基础但特别救命的小习惯分享给你第一安装前先做一个系统还原点Windows或快照Linux。Texlive 安装过程会写入大量文件到系统目录如果你后续误操作删了关键文件还原点能让你十分钟回到安全状态省掉一晚上的重装时间。第二保留安装日志。Texlive 安装器在执行时会把详细过程写到 install-tl.log 文件里很多人不看它。实际上报错的最终原因往往埋在日志的最后一百行里。排查时先打开日志按ERROR、Warning过滤再定位问题比空想强得多。第三独立建一个工作目录用来做编译验证。我从来不在.bashrc里测试文档而是在/tmp或者一个临时文件夹里测试编译。这样做的好处是如果配置有问题也不会污染你的正式论文目录。写在结尾那次已解决的复盘回到开头那次排查。朋友最终在 11 点 14 分编译出了第一份中文 PDF他在电话里明显松了一口气。复盘整个过程问题根本不在 TeX Live 本身而在三个叠加的环境因素解压工具破坏了安装器脚本、杀毒软件拦截了批量文件创建、默认官方仓库连接超时。每一条单独拿出来都不算难题但叠在一起就会让人产生这软件是不是有毛病的绝望感。如果你现在正卡在某个安装报错前我的建议是把报错信息完整读一遍它是你排查的起点然后按镜像源、磁盘空间、解压完整性、PATH 路径这四个步骤逐层排查不要图快。TeX Live 已经是所有主流发行版里安装逻辑非常标准的软件了只要环境干净、步骤正确一次装通并不是什么难事。