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 -h（Linux/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，或者Can't 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 已经是所有主流发行版里安装逻辑非常标准的软件了，只要环境干净、步骤正确，一次装通并不是什么难事。
