texlive2023的安装是个看起来十分钟能搞定、实际上能让不少人耗掉一整个下午的活儿。我自己前后在不同机器上装过七八次从 Win7 老笔记本到 M1 的 Mac再到公司的 Linux 服务器每一次踩的坑都不太一样。这篇就把整个过程摊开讲从下载安装器开始到第一份中文 PDF 顺利编译出来为止中间每一个会让你卡住的环节我都标出来。如果你是第一次接触 LaTeX完全照着走就行如果你以前装过旧版本、想升级到 texlive2023 或者重装一遍干净环境那第二、四、六章对你更有用尤其是仓库地址那块——2023 已经归档了直接照老教程里的地址敲十有八九会报错。我会把 Windows、macOS、Linux 三条路都写清楚你可以只看自己系统那一节但建议顺手瞟一眼其他平台的差异点能省掉不少为什么我的命令不生效的困惑。1. 装之前先算账这套东西到底占多少资源很多人卡在第一步不是因为技术问题而是心理准备不足——以为 TeX Live 跟装个记事本差不多点下一步就完了结果发现它要吃掉七八个 G 的硬盘空间下载还要跑一两个小时。所以先把账算清楚你才知道该选哪个安装方案。1.1 完整版、精简版、发行版自带包三条路的取舍TeX Live 官方提供的是scheme 方案这一层的选择最主流的是两个scheme-full和scheme-minimal。前者把 CTAN 上九成以上的宏包、字体、文档全部拉下来装完大概 7 到 8 个 G后者只有最基础的一套内核和少量工具两百兆左右之后你想要什么包再用tlmgr install xxx单独装。那到底该选哪个我的建议很直接硬盘不是特别紧张就上完整版。原因有三个。第一LaTeX 的报错里最难缠的就是File xxx.sty not found精简版安装会让你在写论文的半夜频繁遇到它然后被迫中断写作去查这个包叫什么、装哪个。第二完整版自带的字体和宏包版本是经过整体测试的不容易出现宏包之间版本打架。第三tlmgr单独装包时经常要处理依赖虽然它会自动拉依赖但网络一抖就容易装到一半失败折腾时间远比多下几个 G 更贵。反过来说如果你只是偶尔用用、机器上已经有一个 TeX 发行版比如 macOS 上想装个 BasicTeX 做补充那精简路线也不是不行。我有一台老笔记本就是装的 minimal日常写个简历、排个简单文档完全够用。1.2 在线安装器、ISO 镜像、系统包管理器三种形态怎么选官方的安装文件主要有三种形态很多人下载时看着一堆名字就懵了安装形态典型文件名体积适合场景在线安装器install-tl-windows.exe/install-tl.zip20MB 左右网络稳定想装最新版本完整 ISO 镜像texlive2023.iso约 5.5GB网络差、要离线装、要批量部署系统包管理器apt install texlive-full之类视仓库而定服务器上快速拉起环境在线安装器只包含一个引导程序真正的内容是边装边从镜像站下载的。它的优点是体积小、随时能拿到最新的宏包快照缺点是中断就得重来而且对网络波动的容忍度很低。ISO 镜像则是把当年发布时的全部内容打包好下载完挂载或者解压安装过程中完全不联网稳定性最好缺点是版本固定在发布那一刻后续要更新还是得联网。系统包管理器那条路比如 Debian/Ubuntu 的texlive-full装起来最快但版本跟你系统的仓库绑定可能根本不是 2023 版而且卸载起来比较麻烦宏包的更新也跟着系统走不够灵活。我的实际选择是家用机用在线安装器 国内镜像站服务器上用 ISO 或者静默安装追求一次搞定。注意如果你打算用在线安装器务必先把镜像仓库地址改成国内站点再开始装。默认走官方源在国内环境下光下载就可能耗掉半天而且中途断线概率很高。1.3 时间与空间的实测数据我在一台 NVMe 固态的 Windows 机器上装完整版全程约 18 分钟同一台机器如果是纯机械硬盘实测要 55 分钟往上主要是解压大量小文件时磁盘随机读写拖后腿。Mac 上装 MacTeX 快一些因为安装包是预打包好的大约 10 到 15 分钟。Linux 服务器上用静默安装配上国内镜像20 分钟左右。空间方面给个参考完整版含文档和源码Windows 下默认装在C:\texlive\2023实际占用 7.6GB 左右。如果你在 profile 里关掉文档和源码能省下大概 2.5GB。这个取舍我后面会讲怎么操作。2. Windows 平台图形界面安装器逐项拆解Windows 用户是大多数所以我这块写得细一点。整个流程分下载校验、安装配置、环境验证三步其中第二步里有四个开关是决定你后面顺不顺的关键。2.1 下载与校验别在第一步就翻车去 CTAN 或者国内镜像站的systems/texlive/tlnet/目录下找install-tl-windows.exe。这个文件只有二十来兆但它是引导器不是完整包。下载完之后一定要做一件事核对体积和文件名。我遇到过朋友从某个第三方下载站拿到的安装器只有 3MB装完发现是个捆绑软件这时候再清理就很烦。校验的办法很简单在文件所在目录打开 PowerShellGet-FileHash .\install-tl-windows.exe -Algorithm SHA512然后跟镜像站同目录下sha512.sum文件里对应的那一行比对。这一步大概花你三十秒但能避免后面所有麻烦。下载完之后右键选择以管理员身份运行。这一步不是可选项因为安装器要往系统 PATH 里写东西、要创建全局目录权限不够会在末尾报一堆莫名其妙的错误。2.2 自定义安装里的四个关键开关图形界面点开之后先看到的是欢迎页接着是安装方案选择。默认勾的是scheme-full如果你硬盘够保持默认。往下展开自定义有几个地方值得动手第一个开关是安装 TeXworks。TeXworks 是自带编辑器功能比较基础如果你打算用 VS Code 或者 TeXstudio可以取消勾选省点空间也少个干扰项。第二个开关是调整搜索路径。默认是勾上的它会自动把 TeX Live 的 bin 目录写进系统环境变量。这个必须保持勾选否则你装完之后在命令行敲tex --version会提示找不到命令。第三个是安装文档和源码的选项。在自定义界面里找到tlpdbopt_install_docfiles和tlpdbopt_install_srcfiles这两个开关图形界面里对应的是两个复选框。关掉它们能省 2GB 多代价是你没法用texdoc直接查宏包手册。我个人的做法是文档保留源码关掉。文档是学习资源源码基本用不上除非你要改宏包本身。第四个是安装路径。默认C:\texlive\2023建议别改。因为 TeX 生态里有大量脚本硬编码了这个默认路径改到带空格或者中文的目录下后面很容易出幺蛾子。如果你 C 盘真的紧张我建议是装完后再做目录链接而不是直接在安装器里改路径。设置完之后点安装接下来就是等待。这期间安装器会显示一个滚动的日志窗口里面刷的各种[1/3000]之类的进度。不要在这个阶段点关闭按钮哪怕它看起来卡住不动了。下载大文件时进度条会停几分钟这是正常的。2.3 静默安装一次写好 profile批量部署如果你要给实验室几台机器装一样的配置图形界面一台台点太蠢了。TeX Live 支持用 profile 文件做无人值守安装这个技巧值得记下来。先在任意一台机器上完成一次图形安装然后到C:\texlive\2023\tlpkg\目录下找生成的 profile 文件或者你自己写一个内容大概长这样selected_scheme scheme-full TEXDIR C:/texlive/2023 TEXMFCONFIG ~/.texlive2023/texmf-config TEXMFHOME ~/texmf TEXMFLOCAL C:/texlive/texmf-local TEXMFSYSVAR C:/texlive/2023/texmf-var TEXMFSYSCONFIG C:/texlive/2023/texmf-config TEXMFVAR ~/.texlive2023/texmf-var instopt_adjustpath 1 instopt_adjustrepo 1 tlpdbopt_install_docfiles 1 tlpdbopt_install_srcfiles 0注意路径分隔符用正斜杠Windows 下也这么写TeX Live 自己会处理。然后.\install-tl-windows.exe -no-gui -profile .\texlive.profile这一行命令就能把整套东西装完。-no-gui表示不弹界面-profile指定配置文件。整个过程没有交互适合写进批处理脚本里。我给我们组里三台机器部署时就是这么干的第一次装完记下 profile后面直接复用省事。3. macOS 与 Linux命令行才是主战场这两个平台的情况跟 Windows 不太一样尤其是 macOS它的安装包形态跟 Windows 差得挺远很多人第一次装会困惑该选哪个。3.1 macOS 的三条路线怎么挑macOS 上主流选择是MacTeX和BasicTeX。MacTeX 是一个完整的 pkg 安装包体积大约 5.5GB装完之后实际上就是 TeX Live 的完整版只是套了个 Mac 友好的壳还会顺手给你装 TeXShop 编辑器和一些额外工具。BasicTeX 只有一百多兆装完之后你需要自己用tlmgr补包。我个人的判断标准是主力机一定装 MacTeX因为省心而且它的安装位置是/usr/local/texlive/2023PATH 由安装包自动通过/Library/TeX/texbin这个软链暴露出来基本不需要手动配。BasicTeX 我一般只装在临时环境或者 CI 的容器里因为它要补的包太多了装一次完整版反而更快。安装过程没什么好说的双击 pkg一路下一步。要注意的是macOS 的新版本可能会拦截未签名或旧签名的安装包如果双击后提示无法打开因为它来自身份不明的开发者去系统设置 → 隐私与安全性里找到那条拦截记录点仍要打开。不是让你关掉整个安全策略只是针对这一个安装包放行。装完之后验证which tex tex --version如果which tex返回/Library/TeX/texbin/tex就说明路径接好了。如果什么都没返回检查一下/Library/TeX/texbin在不在 PATH 里echo $PATH | tr : \n | grep texbin没有的话在你的~/.zshrc或者~/.bash_profile里加一行export PATH/Library/TeX/texbin:$PATH3.2 Linux 下用静默参数一次装到位Linux 上基本都是命令行安装我一般直接下载install-tl-unx.tar.gz解压后进目录执行。想省事就直接上 scheme-full配合国内镜像cd /tmp wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/install-tl-unx.tar.gz tar -xzf install-tl-unx.tar.gz cd install-tl-*/ sudo ./install-tl -repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/ -scheme full -no-interaction-repository指定镜像源-scheme full选完整方案-no-interaction表示全自动不询问。默认安装位置是/usr/local/texlive/2023。装完之后PATH 需要自己处理。Linux 下不会自动帮你改环境变量除非你在安装时选择了创建符号链接。我倾向于手动加写进/etc/profile.d/texlive.shexport PATH/usr/local/texlive/2023/bin/x86_64-linux:$PATH export MANPATH/usr/local/texlive/2023/texmf-dist/doc/man:$MANPATH export INFOPATH/usr/local/texlive/2023/texmf-dist/doc/info:$INFOPATH注意x86_64-linux这个目录名在不同架构下不一样ARM 服务器上会是aarch64-linux。你可以先ls /usr/local/texlive/2023/bin/看一眼实际名字别硬抄。注意直接export PATH只对当前终端会话生效关掉就没了。写进 profile 之后要source /etc/profile.d/texlive.sh或者重新登录才生效。我见过有人改完 PATH 立刻在新终端里测试结果死活找不到命令就是漏了这一步。3.3 三平台关键差异对照把差异集中列一下方便你对照自己的环境对比项WindowsmacOSLinux安装文件install-tl-windows.exeMacTeX.pkginstall-tl-unx.tar.gz默认安装路径C:\texlive\2023/usr/local/texlive/2023/usr/local/texlive/2023PATH 是否自动配是勾选 adjustpath是经 /Library/TeX/texbin否需手动bin 目录名windowsuniversal-darwinx86_64-linux / aarch64-linux卸载方式官方 uninstall 脚本官方脚本 手动清软链手动删目录 清 profile表格里最后一行值得展开说。TeX Live 的自带卸载脚本在 Windows 和 macOS 上都有但它不会清干净你用户目录下的配置比如~/.texlive2023这一坨缓存。重装之前如果不删掉偶尔会出现新旧配置冲突导致的奇怪报错。这一点我在第六章还会提到。4. tlmgr装完之后真正天天打交道的工具安装只是入场券真正跟你长期相处的是tlmgrTeX Live Manager。补包、升级、回滚、查包全靠它。这个工具用好能省掉大量这个宏包在哪的搜索时间。4.1 换源把下载速度从龟速拉到满速默认仓库是官方的国内访问速度感人。第一件事就是换到国内镜像tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/执行完会提示tlmgr: setting default package repository to ...。想看当前用的是哪个源直接tlmgr option repository常用的几个镜像站地址都指向 CTAN 的 tlnet 目录你可以按自己的网络情况挑https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/https://mirrors.ustc.edu.cn/CTAN/systems/texlive/tlnet/https://mirrors.aliyun.com/CTAN/systems/texlive/tlnet/我的经验是这三个都不慢清华的同步频率最高中科大偶尔在某些运营商线路下更快。如果你下载时发现速度只有几十 KB换一个再试别硬扛。4.2 texlive2023 已经归档仓库地址得改这是个特别容易踩的坑必须单独说。TeX Live 是滚动发布的每年三四月份出新版本现在已经是 2024、2025 了新版本发布之后上一年的版本会从活跃仓库里移走进入归档区同时停止更新。这意味着什么如果你现在装的是 texlive2023然后照着一篇老教程敲了上面那条tlnet/地址执行更新很可能会遇到类似这样的报错tlmgr: Local TeX Live (2023) is older than remote repository (2025). Cross release updates are only supported with update-tlmgr-latest(.sh/.exe) --update这个提示的意思就是你本地的版本比远程仓库老了跨版本更新它不支持。解决办法不是去跑那个update-tlmgr-latest——那玩意儿容易搞坏环境——而是把仓库地址改成 2023 对应的归档地址tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/2023/tlnet-final路径里的关键是那个2023/tlnet-final表示 2023 这个版本的最终快照。改成这个之后tlmgr update --all就能正常跑只是你能拿到的永远是 2023 停止维护那一刻的包状态不会再往后走。如果镜像站上没有这个路径就去 CTAN 的归档区找不同镜像的目录结构会有点差别有的把历史版本放在CTAN/systems/texlive/下有的单独开一个 historic 目录。实在找不到就换一个镜像站试。注意跨版本更新这个雷在每年新版本发布之后的半年内踩的人最多。如果你不是非 2023 不可直接装最新版更省事。但如果你的项目、论文模板、服务器环境锁定在 2023那就老老实实用归档地址别想着升一下说不定没事。4.3 常用命令清单与更新节奏tlmgr的命令不算多掌握下面这几个基本够用tlmgr update --self # 先更新 tlmgr 自身 tlmgr update --all # 更新所有已安装宏包 tlmgr install geometry # 装单个宏包 tlmgr install collection-langchinese # 装中文字相关的整个集合 tlmgr remove 包名 # 卸载 tlmgr info 包名 # 查看包信息、版本、依赖 tlmgr search --global --file caption.sty # 反查某个 sty 文件属于哪个包 tlmgr restore 包名 版本号 # 回滚到指定版本最后那两条是我用得最多的。search --file能直接告诉你caption.sty来自caption包省掉去 CTAN 网站翻页的功夫。restore则是救命稻草——偶尔更新完某个包之后编译报错用它回滚到上一个版本比在那儿排查半天快得多。更新节奏上我的建议是别跟自动更新。宏包更新偶尔会引入不兼容尤其是你正在写论文的档口一个包更新完编译突然挂了那滋味不好受。我的做法是项目deadine 前一周不更新等交了稿再统一升一次。5. 编辑器与中文字体让第一份 PDF 顺利跑出来环境装好了命令行也能敲出tex --version了但这还不算完。真正干活得配编辑器而中文用户还多一道字体缓存的坎。5.1 VS Code 加 LaTeX Workshop 的最小可用配置VS Code 是现在最主流的选择装个LaTeX Workshop扩展就行。但默认配置对中文用户不太友好需要改几处。打开设置切到 JSON 编辑模式把这几段加进去{ latex-workshop.latex.recipes: [ { name: xelatex x2, tools: [xelatex, xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ], latex-workshop.latex.autoClean.run: onBuilt, latex-workshop.latex.clean.fileTypes: [ *.aux, *.bbl, *.blg, *.idx, *.ind, *.lof, *.lot, *.out, *.toc, *.fls, *.log, *.fdb_latexmk, *.synctex.gz ] }为什么用xelatex而不是pdflatex因为中文排版基本绕不开 XeLaTeX 这条链路它对系统字体的调用最直接ctex宏包也是优先支持它。-synctex1是给正向反向跳转用的点 PDF 能跳回源码、点源码能跳到 PDF 位置写长文档必备。-interactionnonstopmode让编译出错时不要停下来等你敲回车否则自动化流程会卡死。-file-line-error让报错信息里带上行号定位错误快很多。最后那段clean.fileTypes是让它在编译成功后自动清理中间文件。不配的话一个目录里塞满各种 aux、log、out看着糟心。5.2 TeXstudio 的可复现编译链如果你不喜欢 VS Code 那一堆配置TeXstudio 更开箱即用。装完之后进选项 → 构建把默认编译器改成 XeLaTeX。命令那一栏改成xelatex -synctex1 -interactionnonstopmode -file-line-error %.tex如果你要处理参考文献建议用latexmk做统一调度它能自动判断要不要跑 bibtex、要跑几遍。在构建里把默认构建命令设成latexmk -xelatex -synctex1 -interactionnonstopmode %.texlatexmk是 TeX Live 自带的不用额外装它会把整个编译流程该跑几遍跑几遍省得你手动点三次编译。这个是我强烈推荐的尤其是处理带交叉引用和参考文献的文档。5.3 中文排版的字体缓存坑中文字体这块有个经典问题你明明装了字体代码里也写了字体名编译却报找不到。原因通常是XeLaTeX 依赖系统字体缓存而 TeX Live 有自己的字体数据库两者有时候对不上。最小测试文档\documentclass[UTF8]{ctexart} \begin{document} 你好世界。这是一段中文排版测试。 \end{document}用xelatex main.tex编译。如果这一步就报The font SimSun cannot be found之类的错按下面的顺序排查。第一步刷新 TeX Live 自己的字体缓存luaotfload-tool --update这个命令会重建 LuaTeX/XeLaTeX 用的字体索引中文环境下尤其重要因为它对系统字体的识别依赖这个索引。第二步确认字体在系统里真实存在。Windows 下fc-list :langzhmacOS 下用字体册搜一下Linux 上fc-list :langzh | head。如果系统里压根没这个字体那当然是找不到。第三步如果系统有但 TeX 找不到试试用字体文件名而不是字体名来引用。比如把\setCJKmainfont{SimSun}改成\setCJKmainfont{simsun.ttc}有时候字体名和实际文件名的匹配会出问题直接指定文件名更可靠。这个细节很少有教程提到但我自己撞过两次。注意在 Docker 容器或者精简的 Linux 镜像里跑 XeLaTeX最常见的问题就是镜像里没有中文字体。这时候不是你配置错了而是真的缺字体文件。解决办法是装一套开源中文字体比如fonts-noto-cjk然后再刷新缓存。6. 报错排查实录与避坑清单前面把正常流程走完了这一章专门讲不正常的情况。这些都是我自己或身边人真实遇到过的按出现频率排。6.1 安装阶段的问题安装到一半断网重装报错。这是最典型的。TeX Live 的安装目录被写入了一半再次运行安装器时它会检测到已有目录可能直接跳过一部分或者报冲突。稳妥的做法是先把C:\texlive\2023整个删掉同时删掉%USERPROFILE%\.texlive2023这个用户配置目录然后再重装。只删安装目录不清用户目录偶尔还是会带着旧状态跑。装完之后命令行找不到 tex。八成是 PATH 没生效。Windows 下改环境变量之后必须重开一个新的命令行窗口旧窗口里的 PATH 是启动那一刻的快照不会自动刷新。这个坑极高频很多人在这里怀疑人生。安装器里进度卡在某个百分比很久。先看网络是不是走的官方源。切到国内镜像后下载速度会稳定很多。如果已经切了还卡看一下是不是某个大包比如字体包在下载那种动辄几百兆慢一点正常。磁盘空间不足。完整版装到一半提示空间不够这事挺尴尬。装之前用df -hLinux/macOS或者看 C 盘属性留出至少 10GB 余量比较稳别卡着 8GB 装。6.2 编译阶段的问题File xxx.sty not found。这是 LaTeX 报错里的常驻嘉宾。解决流程很简单先反查这个文件属于哪个包tlmgr search --global --file xxx.sty然后tlmgr install 包名。如果搜索也搜不到说明这个包不在 CTAN 上可能是某个期刊模板自带的得去模板包里翻。编译卡住不动也不报错。常见原因是代码里有个没闭合的括号或者\input的文件不存在LaTeX 在那儿等输入。加了-interactionnonstopmode之后通常就不会卡了会直接报错退出。另一个可能是在下载缺失的包TeX 有自动装包机制网络不好时会卡在那里可以在配置里关掉自动安装。中文变成方框或者乱码。两种可能字体没找到回到 5.3 节的排查流程或者编译引擎选错了。用pdflatex编译含中文的 ctex 文档大概率出问题换成xelatex或lualatex。参考文献编号全变成问号。这是经典的要跑第二遍。引用关系第一遍编译只是记录下来第二遍才会替换成正确的编号。用latexmk就不用管这个它会自己判断跑几遍。6.3 常见问题速查表把上面这些整理成表出问题的时候直接对照报错或现象大概率原因处理办法命令行找不到 texPATH 未生效重开终端检查环境变量Local TeX Live is older仓库指向了新版换成 2023/tlnet-final 归档地址字体 cannot be found字体缓存未刷新luaotfload-tool --update确认字体存在File xxx.sty not found缺宏包tlmgr search --file 反查后 install参考文献显示问号编译次数不够用 latexmk 或手动跑两遍中文显示为方框引擎或字体问题换 xelatex检查字体名安装器中途中断网络波动清目录后重装改用国内镜像编译卡住无响应语法未闭合或等待输入加 -interactionnonstopmode检查括号最后再补一个不太起眼但很实用的技巧给每个项目单独建一个文件夹把.latexmkrc放进去。里面写一行$pdf_mode 5;和$xelatex xelatex -synctex1 -interactionnonstopmode %O %S;这样你在这个目录下直接敲latexmk它就自动用 XeLaTeX 编译不用每次带一长串参数。我在投稿那几个月里靠这个小文件省了大量重复敲命令的时间。 
长河君 · 2026/10/1 5:35:04 · 阅读 1.2k TeX Live 2023 跨平台安装与中文排版避坑指南
texlive2023的安装是个看起来十分钟能搞定、实际上能让不少人耗掉一整个下午的活儿。我自己前后在不同机器上装过七八次从 Win7 老笔记本到 M1 的 Mac再到公司的 Linux 服务器每一次踩的坑都不太一样。这篇就把整个过程摊开讲从下载安装器开始到第一份中文 PDF 顺利编译出来为止中间每一个会让你卡住的环节我都标出来。如果你是第一次接触 LaTeX完全照着走就行如果你以前装过旧版本、想升级到 texlive2023 或者重装一遍干净环境那第二、四、六章对你更有用尤其是仓库地址那块——2023 已经归档了直接照老教程里的地址敲十有八九会报错。我会把 Windows、macOS、Linux 三条路都写清楚你可以只看自己系统那一节但建议顺手瞟一眼其他平台的差异点能省掉不少为什么我的命令不生效的困惑。1. 装之前先算账这套东西到底占多少资源很多人卡在第一步不是因为技术问题而是心理准备不足——以为 TeX Live 跟装个记事本差不多点下一步就完了结果发现它要吃掉七八个 G 的硬盘空间下载还要跑一两个小时。所以先把账算清楚你才知道该选哪个安装方案。1.1 完整版、精简版、发行版自带包三条路的取舍TeX Live 官方提供的是scheme 方案这一层的选择最主流的是两个scheme-full和scheme-minimal。前者把 CTAN 上九成以上的宏包、字体、文档全部拉下来装完大概 7 到 8 个 G后者只有最基础的一套内核和少量工具两百兆左右之后你想要什么包再用tlmgr install xxx单独装。那到底该选哪个我的建议很直接硬盘不是特别紧张就上完整版。原因有三个。第一LaTeX 的报错里最难缠的就是File xxx.sty not found精简版安装会让你在写论文的半夜频繁遇到它然后被迫中断写作去查这个包叫什么、装哪个。第二完整版自带的字体和宏包版本是经过整体测试的不容易出现宏包之间版本打架。第三tlmgr单独装包时经常要处理依赖虽然它会自动拉依赖但网络一抖就容易装到一半失败折腾时间远比多下几个 G 更贵。反过来说如果你只是偶尔用用、机器上已经有一个 TeX 发行版比如 macOS 上想装个 BasicTeX 做补充那精简路线也不是不行。我有一台老笔记本就是装的 minimal日常写个简历、排个简单文档完全够用。1.2 在线安装器、ISO 镜像、系统包管理器三种形态怎么选官方的安装文件主要有三种形态很多人下载时看着一堆名字就懵了安装形态典型文件名体积适合场景在线安装器install-tl-windows.exe/install-tl.zip20MB 左右网络稳定想装最新版本完整 ISO 镜像texlive2023.iso约 5.5GB网络差、要离线装、要批量部署系统包管理器apt install texlive-full之类视仓库而定服务器上快速拉起环境在线安装器只包含一个引导程序真正的内容是边装边从镜像站下载的。它的优点是体积小、随时能拿到最新的宏包快照缺点是中断就得重来而且对网络波动的容忍度很低。ISO 镜像则是把当年发布时的全部内容打包好下载完挂载或者解压安装过程中完全不联网稳定性最好缺点是版本固定在发布那一刻后续要更新还是得联网。系统包管理器那条路比如 Debian/Ubuntu 的texlive-full装起来最快但版本跟你系统的仓库绑定可能根本不是 2023 版而且卸载起来比较麻烦宏包的更新也跟着系统走不够灵活。我的实际选择是家用机用在线安装器 国内镜像站服务器上用 ISO 或者静默安装追求一次搞定。注意如果你打算用在线安装器务必先把镜像仓库地址改成国内站点再开始装。默认走官方源在国内环境下光下载就可能耗掉半天而且中途断线概率很高。1.3 时间与空间的实测数据我在一台 NVMe 固态的 Windows 机器上装完整版全程约 18 分钟同一台机器如果是纯机械硬盘实测要 55 分钟往上主要是解压大量小文件时磁盘随机读写拖后腿。Mac 上装 MacTeX 快一些因为安装包是预打包好的大约 10 到 15 分钟。Linux 服务器上用静默安装配上国内镜像20 分钟左右。空间方面给个参考完整版含文档和源码Windows 下默认装在C:\texlive\2023实际占用 7.6GB 左右。如果你在 profile 里关掉文档和源码能省下大概 2.5GB。这个取舍我后面会讲怎么操作。2. Windows 平台图形界面安装器逐项拆解Windows 用户是大多数所以我这块写得细一点。整个流程分下载校验、安装配置、环境验证三步其中第二步里有四个开关是决定你后面顺不顺的关键。2.1 下载与校验别在第一步就翻车去 CTAN 或者国内镜像站的systems/texlive/tlnet/目录下找install-tl-windows.exe。这个文件只有二十来兆但它是引导器不是完整包。下载完之后一定要做一件事核对体积和文件名。我遇到过朋友从某个第三方下载站拿到的安装器只有 3MB装完发现是个捆绑软件这时候再清理就很烦。校验的办法很简单在文件所在目录打开 PowerShellGet-FileHash .\install-tl-windows.exe -Algorithm SHA512然后跟镜像站同目录下sha512.sum文件里对应的那一行比对。这一步大概花你三十秒但能避免后面所有麻烦。下载完之后右键选择以管理员身份运行。这一步不是可选项因为安装器要往系统 PATH 里写东西、要创建全局目录权限不够会在末尾报一堆莫名其妙的错误。2.2 自定义安装里的四个关键开关图形界面点开之后先看到的是欢迎页接着是安装方案选择。默认勾的是scheme-full如果你硬盘够保持默认。往下展开自定义有几个地方值得动手第一个开关是安装 TeXworks。TeXworks 是自带编辑器功能比较基础如果你打算用 VS Code 或者 TeXstudio可以取消勾选省点空间也少个干扰项。第二个开关是调整搜索路径。默认是勾上的它会自动把 TeX Live 的 bin 目录写进系统环境变量。这个必须保持勾选否则你装完之后在命令行敲tex --version会提示找不到命令。第三个是安装文档和源码的选项。在自定义界面里找到tlpdbopt_install_docfiles和tlpdbopt_install_srcfiles这两个开关图形界面里对应的是两个复选框。关掉它们能省 2GB 多代价是你没法用texdoc直接查宏包手册。我个人的做法是文档保留源码关掉。文档是学习资源源码基本用不上除非你要改宏包本身。第四个是安装路径。默认C:\texlive\2023建议别改。因为 TeX 生态里有大量脚本硬编码了这个默认路径改到带空格或者中文的目录下后面很容易出幺蛾子。如果你 C 盘真的紧张我建议是装完后再做目录链接而不是直接在安装器里改路径。设置完之后点安装接下来就是等待。这期间安装器会显示一个滚动的日志窗口里面刷的各种[1/3000]之类的进度。不要在这个阶段点关闭按钮哪怕它看起来卡住不动了。下载大文件时进度条会停几分钟这是正常的。2.3 静默安装一次写好 profile批量部署如果你要给实验室几台机器装一样的配置图形界面一台台点太蠢了。TeX Live 支持用 profile 文件做无人值守安装这个技巧值得记下来。先在任意一台机器上完成一次图形安装然后到C:\texlive\2023\tlpkg\目录下找生成的 profile 文件或者你自己写一个内容大概长这样selected_scheme scheme-full TEXDIR C:/texlive/2023 TEXMFCONFIG ~/.texlive2023/texmf-config TEXMFHOME ~/texmf TEXMFLOCAL C:/texlive/texmf-local TEXMFSYSVAR C:/texlive/2023/texmf-var TEXMFSYSCONFIG C:/texlive/2023/texmf-config TEXMFVAR ~/.texlive2023/texmf-var instopt_adjustpath 1 instopt_adjustrepo 1 tlpdbopt_install_docfiles 1 tlpdbopt_install_srcfiles 0注意路径分隔符用正斜杠Windows 下也这么写TeX Live 自己会处理。然后.\install-tl-windows.exe -no-gui -profile .\texlive.profile这一行命令就能把整套东西装完。-no-gui表示不弹界面-profile指定配置文件。整个过程没有交互适合写进批处理脚本里。我给我们组里三台机器部署时就是这么干的第一次装完记下 profile后面直接复用省事。3. macOS 与 Linux命令行才是主战场这两个平台的情况跟 Windows 不太一样尤其是 macOS它的安装包形态跟 Windows 差得挺远很多人第一次装会困惑该选哪个。3.1 macOS 的三条路线怎么挑macOS 上主流选择是MacTeX和BasicTeX。MacTeX 是一个完整的 pkg 安装包体积大约 5.5GB装完之后实际上就是 TeX Live 的完整版只是套了个 Mac 友好的壳还会顺手给你装 TeXShop 编辑器和一些额外工具。BasicTeX 只有一百多兆装完之后你需要自己用tlmgr补包。我个人的判断标准是主力机一定装 MacTeX因为省心而且它的安装位置是/usr/local/texlive/2023PATH 由安装包自动通过/Library/TeX/texbin这个软链暴露出来基本不需要手动配。BasicTeX 我一般只装在临时环境或者 CI 的容器里因为它要补的包太多了装一次完整版反而更快。安装过程没什么好说的双击 pkg一路下一步。要注意的是macOS 的新版本可能会拦截未签名或旧签名的安装包如果双击后提示无法打开因为它来自身份不明的开发者去系统设置 → 隐私与安全性里找到那条拦截记录点仍要打开。不是让你关掉整个安全策略只是针对这一个安装包放行。装完之后验证which tex tex --version如果which tex返回/Library/TeX/texbin/tex就说明路径接好了。如果什么都没返回检查一下/Library/TeX/texbin在不在 PATH 里echo $PATH | tr : \n | grep texbin没有的话在你的~/.zshrc或者~/.bash_profile里加一行export PATH/Library/TeX/texbin:$PATH3.2 Linux 下用静默参数一次装到位Linux 上基本都是命令行安装我一般直接下载install-tl-unx.tar.gz解压后进目录执行。想省事就直接上 scheme-full配合国内镜像cd /tmp wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/install-tl-unx.tar.gz tar -xzf install-tl-unx.tar.gz cd install-tl-*/ sudo ./install-tl -repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/ -scheme full -no-interaction-repository指定镜像源-scheme full选完整方案-no-interaction表示全自动不询问。默认安装位置是/usr/local/texlive/2023。装完之后PATH 需要自己处理。Linux 下不会自动帮你改环境变量除非你在安装时选择了创建符号链接。我倾向于手动加写进/etc/profile.d/texlive.shexport PATH/usr/local/texlive/2023/bin/x86_64-linux:$PATH export MANPATH/usr/local/texlive/2023/texmf-dist/doc/man:$MANPATH export INFOPATH/usr/local/texlive/2023/texmf-dist/doc/info:$INFOPATH注意x86_64-linux这个目录名在不同架构下不一样ARM 服务器上会是aarch64-linux。你可以先ls /usr/local/texlive/2023/bin/看一眼实际名字别硬抄。注意直接export PATH只对当前终端会话生效关掉就没了。写进 profile 之后要source /etc/profile.d/texlive.sh或者重新登录才生效。我见过有人改完 PATH 立刻在新终端里测试结果死活找不到命令就是漏了这一步。3.3 三平台关键差异对照把差异集中列一下方便你对照自己的环境对比项WindowsmacOSLinux安装文件install-tl-windows.exeMacTeX.pkginstall-tl-unx.tar.gz默认安装路径C:\texlive\2023/usr/local/texlive/2023/usr/local/texlive/2023PATH 是否自动配是勾选 adjustpath是经 /Library/TeX/texbin否需手动bin 目录名windowsuniversal-darwinx86_64-linux / aarch64-linux卸载方式官方 uninstall 脚本官方脚本 手动清软链手动删目录 清 profile表格里最后一行值得展开说。TeX Live 的自带卸载脚本在 Windows 和 macOS 上都有但它不会清干净你用户目录下的配置比如~/.texlive2023这一坨缓存。重装之前如果不删掉偶尔会出现新旧配置冲突导致的奇怪报错。这一点我在第六章还会提到。4. tlmgr装完之后真正天天打交道的工具安装只是入场券真正跟你长期相处的是tlmgrTeX Live Manager。补包、升级、回滚、查包全靠它。这个工具用好能省掉大量这个宏包在哪的搜索时间。4.1 换源把下载速度从龟速拉到满速默认仓库是官方的国内访问速度感人。第一件事就是换到国内镜像tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/执行完会提示tlmgr: setting default package repository to ...。想看当前用的是哪个源直接tlmgr option repository常用的几个镜像站地址都指向 CTAN 的 tlnet 目录你可以按自己的网络情况挑https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/https://mirrors.ustc.edu.cn/CTAN/systems/texlive/tlnet/https://mirrors.aliyun.com/CTAN/systems/texlive/tlnet/我的经验是这三个都不慢清华的同步频率最高中科大偶尔在某些运营商线路下更快。如果你下载时发现速度只有几十 KB换一个再试别硬扛。4.2 texlive2023 已经归档仓库地址得改这是个特别容易踩的坑必须单独说。TeX Live 是滚动发布的每年三四月份出新版本现在已经是 2024、2025 了新版本发布之后上一年的版本会从活跃仓库里移走进入归档区同时停止更新。这意味着什么如果你现在装的是 texlive2023然后照着一篇老教程敲了上面那条tlnet/地址执行更新很可能会遇到类似这样的报错tlmgr: Local TeX Live (2023) is older than remote repository (2025). Cross release updates are only supported with update-tlmgr-latest(.sh/.exe) --update这个提示的意思就是你本地的版本比远程仓库老了跨版本更新它不支持。解决办法不是去跑那个update-tlmgr-latest——那玩意儿容易搞坏环境——而是把仓库地址改成 2023 对应的归档地址tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/2023/tlnet-final路径里的关键是那个2023/tlnet-final表示 2023 这个版本的最终快照。改成这个之后tlmgr update --all就能正常跑只是你能拿到的永远是 2023 停止维护那一刻的包状态不会再往后走。如果镜像站上没有这个路径就去 CTAN 的归档区找不同镜像的目录结构会有点差别有的把历史版本放在CTAN/systems/texlive/下有的单独开一个 historic 目录。实在找不到就换一个镜像站试。注意跨版本更新这个雷在每年新版本发布之后的半年内踩的人最多。如果你不是非 2023 不可直接装最新版更省事。但如果你的项目、论文模板、服务器环境锁定在 2023那就老老实实用归档地址别想着升一下说不定没事。4.3 常用命令清单与更新节奏tlmgr的命令不算多掌握下面这几个基本够用tlmgr update --self # 先更新 tlmgr 自身 tlmgr update --all # 更新所有已安装宏包 tlmgr install geometry # 装单个宏包 tlmgr install collection-langchinese # 装中文字相关的整个集合 tlmgr remove 包名 # 卸载 tlmgr info 包名 # 查看包信息、版本、依赖 tlmgr search --global --file caption.sty # 反查某个 sty 文件属于哪个包 tlmgr restore 包名 版本号 # 回滚到指定版本最后那两条是我用得最多的。search --file能直接告诉你caption.sty来自caption包省掉去 CTAN 网站翻页的功夫。restore则是救命稻草——偶尔更新完某个包之后编译报错用它回滚到上一个版本比在那儿排查半天快得多。更新节奏上我的建议是别跟自动更新。宏包更新偶尔会引入不兼容尤其是你正在写论文的档口一个包更新完编译突然挂了那滋味不好受。我的做法是项目deadine 前一周不更新等交了稿再统一升一次。5. 编辑器与中文字体让第一份 PDF 顺利跑出来环境装好了命令行也能敲出tex --version了但这还不算完。真正干活得配编辑器而中文用户还多一道字体缓存的坎。5.1 VS Code 加 LaTeX Workshop 的最小可用配置VS Code 是现在最主流的选择装个LaTeX Workshop扩展就行。但默认配置对中文用户不太友好需要改几处。打开设置切到 JSON 编辑模式把这几段加进去{ latex-workshop.latex.recipes: [ { name: xelatex x2, tools: [xelatex, xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ], latex-workshop.latex.autoClean.run: onBuilt, latex-workshop.latex.clean.fileTypes: [ *.aux, *.bbl, *.blg, *.idx, *.ind, *.lof, *.lot, *.out, *.toc, *.fls, *.log, *.fdb_latexmk, *.synctex.gz ] }为什么用xelatex而不是pdflatex因为中文排版基本绕不开 XeLaTeX 这条链路它对系统字体的调用最直接ctex宏包也是优先支持它。-synctex1是给正向反向跳转用的点 PDF 能跳回源码、点源码能跳到 PDF 位置写长文档必备。-interactionnonstopmode让编译出错时不要停下来等你敲回车否则自动化流程会卡死。-file-line-error让报错信息里带上行号定位错误快很多。最后那段clean.fileTypes是让它在编译成功后自动清理中间文件。不配的话一个目录里塞满各种 aux、log、out看着糟心。5.2 TeXstudio 的可复现编译链如果你不喜欢 VS Code 那一堆配置TeXstudio 更开箱即用。装完之后进选项 → 构建把默认编译器改成 XeLaTeX。命令那一栏改成xelatex -synctex1 -interactionnonstopmode -file-line-error %.tex如果你要处理参考文献建议用latexmk做统一调度它能自动判断要不要跑 bibtex、要跑几遍。在构建里把默认构建命令设成latexmk -xelatex -synctex1 -interactionnonstopmode %.texlatexmk是 TeX Live 自带的不用额外装它会把整个编译流程该跑几遍跑几遍省得你手动点三次编译。这个是我强烈推荐的尤其是处理带交叉引用和参考文献的文档。5.3 中文排版的字体缓存坑中文字体这块有个经典问题你明明装了字体代码里也写了字体名编译却报找不到。原因通常是XeLaTeX 依赖系统字体缓存而 TeX Live 有自己的字体数据库两者有时候对不上。最小测试文档\documentclass[UTF8]{ctexart} \begin{document} 你好世界。这是一段中文排版测试。 \end{document}用xelatex main.tex编译。如果这一步就报The font SimSun cannot be found之类的错按下面的顺序排查。第一步刷新 TeX Live 自己的字体缓存luaotfload-tool --update这个命令会重建 LuaTeX/XeLaTeX 用的字体索引中文环境下尤其重要因为它对系统字体的识别依赖这个索引。第二步确认字体在系统里真实存在。Windows 下fc-list :langzhmacOS 下用字体册搜一下Linux 上fc-list :langzh | head。如果系统里压根没这个字体那当然是找不到。第三步如果系统有但 TeX 找不到试试用字体文件名而不是字体名来引用。比如把\setCJKmainfont{SimSun}改成\setCJKmainfont{simsun.ttc}有时候字体名和实际文件名的匹配会出问题直接指定文件名更可靠。这个细节很少有教程提到但我自己撞过两次。注意在 Docker 容器或者精简的 Linux 镜像里跑 XeLaTeX最常见的问题就是镜像里没有中文字体。这时候不是你配置错了而是真的缺字体文件。解决办法是装一套开源中文字体比如fonts-noto-cjk然后再刷新缓存。6. 报错排查实录与避坑清单前面把正常流程走完了这一章专门讲不正常的情况。这些都是我自己或身边人真实遇到过的按出现频率排。6.1 安装阶段的问题安装到一半断网重装报错。这是最典型的。TeX Live 的安装目录被写入了一半再次运行安装器时它会检测到已有目录可能直接跳过一部分或者报冲突。稳妥的做法是先把C:\texlive\2023整个删掉同时删掉%USERPROFILE%\.texlive2023这个用户配置目录然后再重装。只删安装目录不清用户目录偶尔还是会带着旧状态跑。装完之后命令行找不到 tex。八成是 PATH 没生效。Windows 下改环境变量之后必须重开一个新的命令行窗口旧窗口里的 PATH 是启动那一刻的快照不会自动刷新。这个坑极高频很多人在这里怀疑人生。安装器里进度卡在某个百分比很久。先看网络是不是走的官方源。切到国内镜像后下载速度会稳定很多。如果已经切了还卡看一下是不是某个大包比如字体包在下载那种动辄几百兆慢一点正常。磁盘空间不足。完整版装到一半提示空间不够这事挺尴尬。装之前用df -hLinux/macOS或者看 C 盘属性留出至少 10GB 余量比较稳别卡着 8GB 装。6.2 编译阶段的问题File xxx.sty not found。这是 LaTeX 报错里的常驻嘉宾。解决流程很简单先反查这个文件属于哪个包tlmgr search --global --file xxx.sty然后tlmgr install 包名。如果搜索也搜不到说明这个包不在 CTAN 上可能是某个期刊模板自带的得去模板包里翻。编译卡住不动也不报错。常见原因是代码里有个没闭合的括号或者\input的文件不存在LaTeX 在那儿等输入。加了-interactionnonstopmode之后通常就不会卡了会直接报错退出。另一个可能是在下载缺失的包TeX 有自动装包机制网络不好时会卡在那里可以在配置里关掉自动安装。中文变成方框或者乱码。两种可能字体没找到回到 5.3 节的排查流程或者编译引擎选错了。用pdflatex编译含中文的 ctex 文档大概率出问题换成xelatex或lualatex。参考文献编号全变成问号。这是经典的要跑第二遍。引用关系第一遍编译只是记录下来第二遍才会替换成正确的编号。用latexmk就不用管这个它会自己判断跑几遍。6.3 常见问题速查表把上面这些整理成表出问题的时候直接对照报错或现象大概率原因处理办法命令行找不到 texPATH 未生效重开终端检查环境变量Local TeX Live is older仓库指向了新版换成 2023/tlnet-final 归档地址字体 cannot be found字体缓存未刷新luaotfload-tool --update确认字体存在File xxx.sty not found缺宏包tlmgr search --file 反查后 install参考文献显示问号编译次数不够用 latexmk 或手动跑两遍中文显示为方框引擎或字体问题换 xelatex检查字体名安装器中途中断网络波动清目录后重装改用国内镜像编译卡住无响应语法未闭合或等待输入加 -interactionnonstopmode检查括号最后再补一个不太起眼但很实用的技巧给每个项目单独建一个文件夹把.latexmkrc放进去。里面写一行$pdf_mode 5;和$xelatex xelatex -synctex1 -interactionnonstopmode %O %S;这样你在这个目录下直接敲latexmk它就自动用 XeLaTeX 编译不用每次带一长串参数。我在投稿那几个月里靠这个小文件省了大量重复敲命令的时间。