Linux下LaTeX环境搭建：TeX Live安装配置与踩坑实战指南-开发者社区

TeX Live 是我在 Linux 上折腾得最久也受益最多的工具之一。以前在 Windows 上写论文，装个完整版 CTex 套装就算完事，但迁移到 Linux 之后才发现，发行版安装、路径配置、字体管理、编译链选择，每一步都有隐藏的坑。这篇内容就是把我这些年踩过的坑、验证过的方法重新梳理一遍，希望能让初到 Linux 的 LaTeX 用户在搭建环境时少走弯路，也让已经在用的人有一些可以优化的思路。

1. LaTeX、TeX 与 TeX Live 的关系：先弄清再动手

先说一个很多人刚开始容易混淆的概念。LaTeX 是基于 TeX 排版的宏包集合，TeX 是底层排版引擎，而 TeX Live 是一个集成了 TeX 引擎、LaTeX 宏包、字体、文档类、辅助工具和文档的完整发行版。类比一下，TeX 相当于编译器，LaTeX 相当于标准库，TeX Live 则相当于把编译器、标准库、依赖管理器和文档打包在一起的 SDK。搞清楚这层关系，后面所有安装和配置的逻辑才能理顺。

我遇到过不少新手，装完 TeX Live 之后以为万事大吉，直接打开编辑器写文档，结果一编译就报错，然后以为是 TeX Live 没装好。实际上，大多数此类问题都不在 TeX Live 本身，而在编辑器配置、编译引擎选择、宏包缺失或字体环境这几个环节。所以，这篇内容我会把从下载安装到日常编译的整个链路都过一遍，重点讲哪些环节最容易出问题、出了问题怎么定位。

2. 安装方式的取舍：在线安装器、发行版仓库与容器化

2.1 为什么我不建议直接用 apt 安装 TeX Live

Linux 发行版仓库里基本都能找到 TeX Live，比如 Debian/Ubuntu 下用 apt install texlive-full 就能装上一整套。但我的建议是：除非你对版本没有要求，否则尽量别这么做。原因有两点。

第一，发行版仓库里的 TeX Live 版本普遍滞后。以我的经验，常见发行版仓库里的版本往往比官方发布晚几个月甚至更久。对于日常写普通文档这影响不大，但如果你投稿的期刊模板更新了宏包，或者需要某个新版宏包才支持的语法，旧版本可能直接就编译不过。

第二，apt 安装的 TeX Live 不带 tlmgr。tlmgr 是 TeX Live 自带的包管理器，负责宏包安装、更新、版本查询。apt 版阉割了这个工具，导致你后续想装缺失的宏包会非常被动，只能手动去 CTAN 下载宏包然后按目录解压，麻烦且容易出错。所以，想要一个长期可控的 TeX Live 环境，我强烈推荐使用官方安装器在线安装。

2.2 在线安装器的完整流程

官方安装器是一个名为 install-tl-unx.tar.gz 的压缩包，从清华大学开源软件镜像站或上海交通大学 Linux 用户组软件源镜像站都能下载。下载解压后，目录下有一个 install-tl 脚本，这就是安装器本体。

安装器支持两种安装模式：交互式安装和无人值守安装。交互式运行直接执行 ./install-tl，会进入一个 TUI 菜单，可以逐项选择安装方案（scheme）、安装目录前缀（TEXDIR）、是否安装全部宏包等，适合首次安装、想看看有哪些选项的用户。但我的习惯是直接用无人值守模式，将安装参数通过命令行传入，这样整个安装流程可以脚本化，团队里每台新机器都能复现同一套安装过程。

一个典型无人值守安装命令大致如下：

cd install-tl-XXXXXXXX ./install-tl --profile /path/to/texlive.profile

其中 texlive.profile 是一个配置文件，内容大概长这样：

selected_scheme scheme-full TEXDIR /usr/local/texlive/2025 TEXMFCONFIG ~/.texlive2025/texmf-config TEXMFHOME ~/texmf TEXMFLOCAL /usr/local/texlive/texmf-local TEXMFSYSCONFIG /usr/local/texlive/2025/texmf-config TEXMFSYSVAR /usr/local/texlive/2025/texmf-var TEXMFVAR ~/.texlive2025/texmf-var option_doc install option_src install

这里我选择了 scheme-full，也就是完整方案，会安装所有宏包和文档。优点是省心，装完基本不会再遇到“缺宏包”的问题；缺点是安装时间较长、占用磁盘空间较大（通常超过 6GB）。如果你只需要写普通中英文论文，可以选择 scheme-medium 甚至 scheme-small，后续有需要再用 tlmgr 补装。

安装目录前缀我习惯设为 /usr/local/texlive，后面接年份，比如 2025。这样做的目的是把不同年份的 TeX Live 隔离在不同目录里，万一某一年出了兼容性问题，可以随时切换回旧版本，而不必卸载重装。

3. 安装完成后的关键配置：PATH、字体与版本验证

3.1 PATH 配置：装完先验证再干别的

安装完成后，bin 目录不会自动加入 PATH。你需要找到类似 /usr/local/texlive/2025/bin/x86_64-linux 的目录，把它追加到 shell 配置文件里。注意，这里 x86_64-linux 是 Intel/AMD 平台的目录名，如果用的是 ARM 架构的机器，目录名是 aarch64-linux。

在 ~/.bashrc 或 ~/.zshrc 中加入：

export PATH=/usr/local/texlive/2025/bin/x86_64-linux:$PATH

然后执行 source ~/.bashrc 使配置生效。我曾亲眼见过有人装完 TeX Live 后直接运行 tex --version 发现 command not found，然后以为安装失败开始重装，结果排查到半夜发现只是没刷新 PATH。所以请务必记住，装完后第一步就是验证三个命令：

tex --version latex --version xetex --version

能正常输出版本信息，说明核心引擎已经可用。如果这里就报错，先回头检查 PATH 和安装目录，不要急着重装。

3.2 字体问题：最常见的“装好了却用不了”的原因

LaTeX 默认使用 Computer Modern 字体，好处是排版效果经典，坏处是如果系统里没有配套的中文字体，或者没有正确调用系统字体，编译出来的 PDF 用别的设备打开就可能字体替换、排版错乱。尤其是在 Linux 服务器上，默认字体环境往往很简陋，中文字体可能一个都没有。

检查系统是否有中文字体，用这个命令：

fc-list :lang=zh

如果输出为空，说明系统没有安装任何中文字体。你需要在系统层面安装字体包，常见的比如 Noto Sans CJK、思源黑体、思源宋体等。Debian/Ubuntu 下大致是：

sudo apt install fonts-noto-cjk

安装后执行 fc-cache -fv 刷新字体缓存。然后在使用 XeLaTeX 或 LuaLaTeX 时，文档中可以通过 fontspec 或 xeCJK 宏包指定中文字体。比如：

\documentclass[UTF8]{ctexart}

这是我最常用的中文方案，ctex 宏包会自动选择系统里可用的中文字体，一般不需要手动指定。但如果编译链是 pdflatex，中文字体的问题就会异常棘手，所以强烈建议中文用户统一使用 xelatex 引擎。

提示：即使系统装了字体，也不要以为 TeX Live 会自动感知。字体缓存更新不及时会反复报“字体找不到”的错误，多执行几次 fc-cache -fv 通常能解决。

4. 宏包管理、镜像源与常见报错排查

4.1 tlmgr 的仓库配置

说到宏包，就离不开 tlmgr。这是 TeX Live 自带的包管理工具，可以安装、更新、查询宏包。但在国内使用 tlmgr，第一件事是配置镜像源，否则连接官方仓库经常超时或速度很慢。

设置仓库地址的命令如下：

tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet

也可以使用中科大镜像：

tlmgr option repository https://mirrors.ustc.edu.cn/CTAN/systems/texlive/tlnet

设置完之后，更新所有宏包：

tlmgr update --all

如果更新时报 404，通常是因为镜像源尚未同步最新索引。这种情况下换一个镜像源试试即可，不用反复重试同一个源。

4.2 旧项目编译失败的排查思路

很多读者会遇到这种场景：从同事或前辈那里拿到一个多年前的 LaTeX 项目，拿到手编译直接报错。这里我给出自己常用的排查链条。

首先确认编译引擎。老项目可能默认用 pdflatex，但如果有中文内容或依赖中文字体，强烈建议直接用 xelatex 编译并修改文档类或宏包设置。其次，检查宏包是否过时。比如 CTeX 宏包老版本在新版 TeX Live 下可能不兼容，直接改成 xeCJK 或 ctex 即可。

一个比较典型的修复过程是：把文档里常用的 CJKutf8、CJK 等老旧宏包替换为 ctex 或 xeCJK，然后编译链切成 xelatex。大多数情况能顺利通过。如果还报错，再看日志中提到的宏包名，用 tlmgr search 查是否还在维护，必要时回退宏包版本：

tlmgr install <package> tlmgr restore <package>

4.3 日志文件的阅读方法

编译报错不要只看终端几行提示，打开生成的 .log 文件。LaTeX 的日志文件非常详细，每次报错都会标注出错的行号和上下文。我每次编译失败，第一反应都是 grep 错误关键词，比如：

grep -n "^!" main.log

以 ! 开头的行是真正的错误
"Overfull hbox" 是排版溢出警告，不是致命错误
"Missing character: There is no ... in font" 表示字体缺字形，常见于用了不支持的特殊符号或表情

学会看日志，能帮你节省大量排查时间。

5. 编辑器与编译链选型：从 VS Code 到 latexmk

5.1 编辑器选择

TeX Live 自带一个轻量编辑器 TeXworks，可以应急用，但我日常更推荐 Visual Studio Code 搭配 LaTeX Workshop 插件。LaTeX Workshop 支持 SyncTeX（源码与 PDF 双向跳转）、自动补全、错误提示、多编译链切换，体验已经非常接近商业编辑器。

如果偏好轻量，也可以直接用 Vim 加 vimtex 插件。Vim 的优点是资源占用低，在服务器上编辑也流畅，但初上手成本高。通过 VS Code 的 Remote-SSH 插件，也可以把 VS Code 当作前端连接到远程服务器，本地编辑、远程编译，适合服务器上跑大型项目的人。

5.2 编译链与 latexmk

很多人写完 LaTeX 文档，习惯手动敲 pdflatex、bibtex、pdflatex、pdflatex 四连编译。这个流程对参考文献和交叉引用更新是必要的，但手动操作容易漏。我的做法是统一用 latexmk 管理编译链。

latexmk 会自动判断需要执行哪些工具、执行多少次。它依赖配置文件 latexmkrc，一个最简单的配置如下：

$pdf_mode = 5; $xdvi_mode = 0; $bibtex_use = 2;

其中 $pdf_mode = 5 表示使用 xelatex 编译并生成 PDF，$bibtex_use = 2 表示需要 bibliography 时自动调用 biber 或 bibtex。这样在 VS Code 里只需按一次编译，latexmk 会处理后面所有步骤。引用一直是问号、参考文献不更新这类经典问题，用 latexmk 基本不会再遇到。

在大型项目里，我还会用 \includeonly{} 只编译当前章节，大幅缩短编译时间。日常修改十几秒完成，只有最终提交时才全量编译。配合这个技巧，写作体验会有质的提升。

6. 容器化部署：让团队成员共享同一套 LaTeX 环境

如果团队成员多、项目持续周期长，我和团队采用的做法是容器化部署。核心思路是把 TeX Live 环境固化成一个镜像，所有人都在这个镜像里编译文档，从源头杜绝版本不一致的问题。这种做法对毕业论文这种“每年一批新学生、环境却要大统一”的场景非常适用。

镜像构建过程可以这样理解：基础镜像从官方 TeX Live 镜像拉取，然后通过 Dockerfile 预装需要的宏包和字体。下面是一个简化的 Dockerfile 结构：

FROM texlive/texlive:latest RUN tlmgr install ctex xeCJK fontspec latexmk RUN apt-get update && apt-get install -y fonts-noto-cjk

不过要注意一点，官方镜像通常只有基础环境，很多宏包需要自己 tlmgr 补装。如果项目已经稳定，建议把 tlmgr install 的结果固定到 Dockerfile 里，后续每次构建都是相同环境。由于 LaTeX 宏包文件很多，镜像构建时缓存优化很关键——把 tlmgr install 这一层放到 Dockerfile 靠后的位置，避免频繁改动触发整层重建。

容器化还有一个额外好处是字体环境可控。Linux 服务器上的字体问题，在容器里可以做到与宿主机无关，只要镜像里预装了字体，编译结果就是一致的。我见过太多人遍布多地的机器上字体不一致导致 PDF 版面不一样的情况，容器化直接把这个变量消除掉了。